ReasonForge - Multi-Agent Creative Studio

🧠 Where ideas are shaped, not guessed.

A structured, responsible, and explainable creative reasoning system powered by Gemini AI

🎯 Overview

ReasonForge is a Multi-Agent Creative Studio that demonstrates how a single Large Language Model (Gemini) can be orchestrated through multiple specialized roles to produce high-quality, explainable creative solutions. This is NOT a chatbot or autonomous agent swarm - it's a controlled creative reasoning architecture inspired by how humans think through complex problems.

✨ Key Features

🧩 10-Stage Reasoning Pipeline - Structured problem-solving process
🛡️ Safety-First Approach - Ethics check before any ideation
🎯 Domain-Specific Intelligence - Adapts to your problem's context
🔍 Explainable Reasoning - Transparent logic at every step
🎨 Professional UI/UX - Modern, responsive interface
⚡ Multi-Key Load Balancing - 10 API keys for reliability
🖼️ Contextual Images - Domain-specific visual representations

🏆 Core Principles

Transparency over Magic - All reasoning steps are visible and explainable
Responsibility over Speed - Quality and safety are prioritized over rapid execution
Structure over Randomness - Deterministic pipeline with clear stage boundaries
Explainability over Metrics - Qualitative reasoning instead of opaque numerical scores

🚀 Quick Start

Prerequisites

Node.js 18+
10 Gemini API keys (for load balancing and fallback)

Installation

Clone the repository

git clone https://github.com/Siddh-2006/ReasonForge.git
cd ReasonForge

Install dependencies
```
npm install
```
Configure API Keys

Edit .env.local and add your 10 Gemini API keys (comma-separated):
```
GEMINI_API_KEYS=key1,key2,key3,key4,key5,key6,key7,key8,key9,key10
```
Get API Keys: Visit Google AI Studio to create your keys
Start the application
```
npm start
```
Open the application

Navigate to http://localhost:3000

🎮 How to Use

Basic Workflow

📝 Enter Your Problem
- Type any complex problem or challenge
- Can be from any domain (business, technology, creative, etc.)
🔍 Clarity Check
- System evaluates problem clarity (0-10 score)
- If score < 7, you'll see clarification questions
- You can skip questions or answer them
🤖 Automated Pipeline
- Safety check ensures ethical compliance
- Domain inference identifies your problem space
- Constraints are generated automatically
- Multiple idea trajectories are explored
- Ideas are critiqued and refined
- Top 3 ideas are ranked and explained
📊 Review Results
- See domain analysis and risk profile
- Review governing constraints
- Explore top 3 ranked ideas with full reasoning
- Click on ideas for detailed analysis

Example Problems

🏢 Business Strategy:

How can we increase customer retention for our SaaS product 
while maintaining profitability and team capacity?

💡 Product Development:

Design an innovative mobile app feature that helps users 
track their carbon footprint without being preachy or overwhelming.

🌱 Agricultural Innovation:

Create a smart irrigation system for small farms that optimizes 
water usage while being affordable for developing regions.

🎨 Creative Challenge:

Create a marketing campaign for a sustainable fashion brand 
that appeals to Gen Z without greenwashing.

🏗️ Architecture

10-Stage Reasoning Pipeline

📥 Problem Intake - Accept user's problem statement
🔍 Clarity Check - Evaluate problem clarity and ask clarifying questions
🛡️ Safety Gate - Detect harmful or unethical intent before ideation
🏢 Domain Inference - Identify problem domain and risk profile
🚧 Constraint Building - Generate governing constraints for ideation
🗜️ Context Compression - Create minimal, high-signal context summary
💡 Idea Generation - Explore multiple creative trajectories (exploratory & constraint-aware)
🔍 Critique - Identify issues using declared constraints
✨ Refinement - Improve ideas based on critiques
🏆 Ranking & Presentation - Select and explain top 3 ideas

Technology Stack

Frontend:

React 19.2.3 with TypeScript
Framer Motion (animations)
Lucide React (icons)
Vite (build tool)
Tailwind CSS (styling)

Backend:

Node.js with Express
Google Generative AI SDK
Multi-key load balancing
Rate limiting
Structured JSON parsing

LLM:

Gemini 2.5 Flash (primary model)
Role-conditioned prompting
Structured output parsing

📁 Project Structure

reasonforge/
├── 📚 docs/                          # Documentation
│   ├── README.md                     # Documentation index
│   ├── TECHNICAL_SPECIFICATION.md    # Complete technical spec
│   ├── CODEBASE_ANALYSIS.md         # Implementation analysis
│   ├── IMPLEMENTATION_SUMMARY.md    # Feature summary
│   ├── API_DOCUMENTATION.md         # Backend API reference
│   └── DEPLOYMENT_GUIDE.md          # Deployment instructions
├── 🔧 backend/
│   ├── api/
│   │   └── creative-studio.js       # ⭐ Core pipeline implementation
│   └── server.js                    # Express server
├── 🎨 services/
│   ├── api-client.ts                # Backend communication
│   └── gemini.ts                    # Frontend service with image generation
├── 📱 App.tsx                       # Main React UI component
├── 📋 types.ts                      # TypeScript interfaces
├── 🚀 index.tsx                     # React entry point
├── 🎨 index.html                    # HTML template with styling
├── ⚙️ vite.config.ts                # Vite configuration
├── 📦 package.json                  # Dependencies and scripts
├── 🔐 .env.local                    # Environment variables (API keys)
├── 🚫 .gitignore                    # Git ignore rules
├── 🌐 vercel.json                   # Vercel deployment config
└── 📖 README.md                     # This file

🔧 Development

Available Scripts

npm run dev - Start frontend development server (port 3000)
npm run backend - Start backend API server (port 3001)
npm start - Start both frontend and backend concurrently
npm run backend:dev - Start backend with auto-reload (nodemon)
npm run build - Build frontend for production
npm run preview - Preview production build

API Key Setup

Why 10 API Keys?

The system uses multiple API keys for:

Load Balancing - Distribute requests across keys
Rate Limit Management - Avoid hitting per-key limits (15 requests/minute/key = 150 total)
Fallback Resilience - Continue working if one key fails

Getting API Keys

Visit Google AI Studio
Create 10 API keys (you can use the same Google account)
Copy each key and add to .env.local separated by commas

Environment Configuration

# Multiple API keys (comma-separated)
GEMINI_API_KEYS=key1,key2,key3,key4,key5,key6,key7,key8,key9,key10

# Rate limiting settings
MAX_REQUESTS_PER_MINUTE=15
FALLBACK_DELAY_MS=2000

# Server configuration
PORT=3001
NODE_ENV=development

🚀 Deployment

Quick Deploy to Vercel (Recommended)

Push to GitHub

git add .
git commit -m "Ready for deployment"
git push origin main

Deploy to Vercel
- Go to vercel.com
- Import your GitHub repository
- Add environment variables (your 10 API keys)
- Deploy!

Configure Environment Variables In Vercel dashboard, add:

GEMINI_API_KEYS=your,ten,api,keys,here
MAX_REQUESTS_PER_MINUTE=15
FALLBACK_DELAY_MS=2000
NODE_ENV=production

Other Deployment Options

Netlify - See Deployment Guide
Custom Server - See Deployment Guide
Docker - See Deployment Guide

📊 Performance

Expected Latency

Clarity Check: 2-3 seconds
Safety Gate: 1-2 seconds
Domain Inference: 2-3 seconds
Constraint Building: 2-3 seconds
Idea Generation: 4-6 seconds (parallel)
Critique & Refinement: 6-8 seconds
Ranking: 2-3 seconds

Total Pipeline: 20-30 seconds of genuine AI reasoning

Optimization Features

Multi-key load balancing (10 API keys = 150 requests/minute capacity)
Parallel execution of exploratory and constraint-aware paths
Context compression to reduce token usage
Automatic fallback handling for resilience
Reliable image generation with domain-specific selection

🔒 Security & Safety

API Key Protection

✅ Keys stored in backend environment only (never exposed to frontend)
✅ Automatic key rotation on failure
✅ Per-key usage tracking and rate limiting

Safety Enforcement

✅ Mandatory safety check before any ideation
✅ Content filtering for harmful intent
✅ Ethical boundary enforcement in constraints
✅ Transparent refusal with explanations

Input Validation

✅ Sanitized user input
✅ Length limits enforced
✅ Injection attack prevention
✅ CORS configuration for allowed origins

🐛 Troubleshooting

Common Issues

Backend won't start:

# Check if port 3001 is in use
netstat -ano | findstr :3001  # Windows
lsof -i :3001                 # Mac/Linux

# Kill the process or change PORT in .env.local

API Key Errors:

Error: All API keys failed

Solution: Verify your API keys are valid and not placeholder values in .env.local

Frontend can't connect to backend:

Failed to fetch

Solution: Ensure backend is running on port 3001 and CORS is enabled

Rate Limit Errors:

Error: All API keys have exceeded rate limits

Solution: Wait 1 minute or add more API keys to .env.local

Debug Commands

# Check backend health
curl http://localhost:3001/api/health

# View backend logs
npm run backend

# Test API endpoint
curl -X POST http://localhost:3001/api/process \
  -H "Content-Type: application/json" \
  -d '{"problem":"test","stage":"clarity"}'

📚 Documentation

📖 Complete Documentation - All technical documentation
🔧 Technical Specification - Detailed architecture and implementation
📊 Codebase Analysis - Code quality and structure assessment
📋 Implementation Summary - Feature overview and status
🌐 API Documentation - Backend API reference
🚀 Deployment Guide - Platform-specific deployment instructions

🤝 Contributing

We welcome contributions! Here's how you can help:

🐛 Report Issues - Found a bug? Open an issue with details
💡 Suggest Features - Have an idea? Share it in discussions
🔧 Submit PRs - Fix bugs or add features with pull requests
📖 Improve Docs - Help make documentation clearer

Development Setup

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and test thoroughly
Commit with clear messages: git commit -m "Add amazing feature"
Push to your fork: git push origin feature/amazing-feature
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Google AI - For the powerful Gemini API
React Team - For the excellent React framework
Vercel - For seamless deployment platform
Tailwind CSS - For the utility-first CSS framework
Framer Motion - For smooth animations
Lucide - For beautiful icons

🌟 Show Your Support

If you find ReasonForge helpful, please consider:

⭐ Starring this repository
🐦 Sharing on social media
💬 Telling others about it
🤝 Contributing to the project

🎯 ReasonForge - Structured Creative Reasoning

Where ideas are shaped, not guessed.

Made with ❤️ by Siddh and Freny

🚀 Try Live Demo • 📚 Read Docs • 🐛 Report Bug • � Request Featuare

Name		Name	Last commit message	Last commit date
api		api
backend		backend
docs		docs
services		services
.gitignore		.gitignore
App.tsx		App.tsx
LICENSE		LICENSE
README.md		README.md
index.html		index.html
index.tsx		index.tsx
metadata.json		metadata.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
types.ts		types.ts
vercel.json		vercel.json
vite-env.d.ts		vite-env.d.ts
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation