🧠 KulturalMente

"Your Mind. Your Culture. Your Story."

🌟 What Makes KulturalMente Special?

Ever wondered why you love certain music, movies, or travel destinations? KulturalMente doesn't just track what you like—it discovers WHY you like it and reveals the deeper cultural story these preferences tell about who you are.

The Problem: We live in a world of scattered cultural preferences with no way to understand the deeper connections between them.

Our Solution: KulturalMente combines Qloo's powerful cultural intelligence with advanced language models to transform scattered preferences into meaningful cultural narratives and personalized discoveries.

✨ Key Features

🎯 Cultural DNA Discovery

5-Domain Analysis: Music, Movies & TV, Food & Dining, Travel & Places, Books & Literature
Smart Search: Qloo-powered auto-suggestions with popularity ratings
Real-time Progress: Track your cultural profile building across domains

🧬 AI-Powered Analysis

Cross-Domain Connections: Discover hidden relationships between your preferences (Music ↔ Movies: 95% strength)
Cultural Narrative Generation: 4-chapter AI stories explaining WHY your preferences connect
Personality Insights: Deep cultural patterns revealed through advanced LLM analysis

🔮 Predictive Intelligence

24-Month Evolution: Predict how your cultural tastes will develop over time
Growth Challenges: Personalized recommendations to expand your cultural horizons
Blind Spot Detection: Identify unexplored cultural territories

🌍 Interactive Visualization

3D Cultural Constellation: Explore your cultural universe in interactive 3D space
Journey Mapping: Visualize connections between cultural preferences
Cultural DNA Explorer: Navigate your cultural identity like never before

📊 Professional Export

Multiple Report Formats: Executive Summary, Detailed Analysis, Technical Report
Real-time PDF Generation: Professional cultural intelligence documents
Social Sharing: Beautiful cultural DNA cards for social media

🛠️ Technology Stack

Core Technologies

Next.js 14 - React framework with App Router and SSR
TypeScript - Type-safe development
Tailwind CSS - Utility-first CSS framework
Framer Motion - Advanced animations and interactions

AI & Data Services

Qloo Taste AI™ API - Cultural intelligence and cross-domain insights
OpenAI GPT-4o - Advanced language model for narrative generation

Additional Libraries

Lucide React - Beautiful icon system
Custom Hooks - Reusable logic for preferences, search, and PDF export

🚀 Quick Start

Prerequisites

Node.js 18+
npm or yarn
Qloo API credentials
OpenAI API key

Installation

Clone the repository

git clone https://github.com/ajitonelsonn/kulturalmente.git
cd kulturalmente

Install dependencies

npm install
# or
yarn install

Set up environment variables Create a .env.local file in the root directory:

QLOO_API_URL=https://api.qloo.com or https://hackathon.api.qloo.com
QLOO_API_KEY=your_qloo_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
NEXT_PUBLIC_APP_NAME=KulturalMente

Run the development server

npm run dev
# or
yarn dev

Open your browser Navigate to http://localhost:3000 to see KulturalMente in action!

🏗️ Architecture Overview

Core Services

Qloo Integration (`qloo-service.ts`)

Search API: Real-time cultural entity search across domains
Similar API: Find related cultural items using Qloo's intelligence
Recommendations API: Generate personalized cultural suggestions
Enhanced Search: Advanced filtering and popularity scoring

AI Narrative Engine (`server-openai-service.ts`)

Cultural Story Generation: Creates meaningful narratives from preferences
Cross-Domain Analysis: Identifies patterns across cultural domains
Evolution Predictions: Forecasts future cultural development
Growth Challenges: Generates personalized expansion opportunities

Cultural Analysis Pipeline

Preference Collection: User inputs across 5 cultural domains
Qloo Processing: Cross-domain entity mapping and relationship analysis
LLM Enhancement: Narrative generation and insight extraction
Visualization: 3D rendering and interactive exploration
Export Generation: Professional report creation

API Endpoints

POST /api/analysis/cultural-profile    # Generate cultural DNA
GET  /api/qloo/search                 # Search cultural entities
GET  /api/qloo/similar                # Get similar entities
POST /api/openai/narrative            # Generate cultural stories
POST /api/openai/discoveries          # Create personalized recommendations

🎯 How It Works

1. Cultural Preference Collection

Users input their favorite items across five domains:

Music: Artists, genres, songs (Eminem, Central Cee, Alan Walker)
Movies & TV: Films, shows, directors (Lion King, Fast & Furious, In Time)
Food & Dining: Cuisines, restaurants, dishes (Casa D'Angelo, Street food, Sushi)
Travel: Destinations, experiences (Los Angeles, Thailand, Turkey)
Books: Authors, genres, titles (LLM Handbook, Naruto)

2. Qloo Intelligence Processing

Entity Mapping: Match user inputs to Qloo's cultural database
Cross-Domain Analysis: Find hidden connections between preferences
Popularity Scoring: Weight preferences by cultural significance
Relationship Strength: Calculate connection strengths (95% Music ↔ Movies)

3. LLM Narrative Generation

Cultural Story Creation: Generate 4-chapter narratives explaining connections
Personality Analysis: Extract deep cultural patterns and themes
Future Predictions: Forecast cultural evolution over 24 months
Growth Opportunities: Identify areas for cultural expansion

4. Visualization & Export

3D Constellation: Interactive exploration of cultural universe
Professional Reports: PDF generation in multiple formats
Social Sharing: Viral-ready cultural DNA cards

📊 Data Flow Architecture

📁 Project Structure

kulturalmente/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── api/               # API routes
│   │   │   ├── analysis/      # Cultural analysis endpoints
│   │   │   ├── qloo/         # Qloo API integration
│   │   │   └── openai/       # OpenAI service endpoints
│   │   ├── onboarding/       # Cultural preference collection
│   │   ├── results/          # Cultural DNA results display
│   │   └── demo/             # Demo page
│   ├── components/           # Reusable React components
│   │   ├── CulturalWowFactor.tsx
│   │   ├── Navigation.tsx
│   │   └── PDFExportModal.tsx
│   ├── hooks/               # Custom React hooks
│   │   ├── use-preferences.ts
│   │   ├── use-search.ts
│   │   └── use-pdf-export.ts
│   └── lib/                 # Core services and utilities
│       ├── qloo-service.ts
│       ├── server-openai-service.ts
│       ├── types.ts
│       └── utils.ts
├── public/                  # Static assets
└── README.md

🌍 Real-World Applications

Personal Development: Understand your cultural identity and growth areas
Travel Planning: Discover destinations aligned with your cultural preferences
Content Discovery: Find books, movies, music that truly resonate
Social Connection: Share and compare cultural DNA with friends
Cultural Education: Learn about global cultural patterns and connections

🚀 Deployment

Deploy to Vercel (Recommended)

KulturalMente is optimized for deployment on Vercel. Follow these steps for a seamless deployment:

Option 1: Deploy via Vercel Dashboard

Push your code to GitHub

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

Import to Vercel
- Visit vercel.com and sign in
- Click "Add New Project"
- Import your GitHub repository
- Vercel will automatically detect Next.js configuration

Configure Environment Variables

In the Vercel project settings, add the following environment variables:

Variable	Value	Description
`QLOO_API_URL`	`https://api.qloo.com` or `https://hackathon.api.qloo.com`	Qloo API endpoint
`QLOO_API_KEY`	`your_qloo_api_key_here`	Your Qloo API credentials
`OPENAI_API_KEY`	`your_openai_api_key_here`	OpenAI API key for narrative generation
`NEXT_PUBLIC_APP_NAME`	`KulturalMente`	Application name

Deploy
- Click "Deploy"
- Vercel will build and deploy your application
- Your app will be live at https://your-project.vercel.app

Option 2: Deploy via Vercel CLI

Install Vercel CLI
```
npm i -g vercel
```
Login to Vercel
```
vercel login
```
Deploy
```
vercel
```
Follow the prompts to configure your deployment.

Set Environment Variables

vercel env add QLOO_API_URL
vercel env add QLOO_API_KEY
vercel env add OPENAI_API_KEY
vercel env add NEXT_PUBLIC_APP_NAME

Deploy to Production
```
vercel --prod
```

Option 3: One-Click Deploy

Click the button above to deploy your own instance of KulturalMente.

Production Build (Manual Deployment)

If you prefer to deploy to other platforms:

npm run build
npm start

Environment Variables for Production

Ensure all environment variables are properly configured:

QLOO_API_URL - Qloo API endpoint (required)
QLOO_API_KEY - Your Qloo API key (required)
OPENAI_API_KEY - OpenAI API key for narrative generation (required)
NEXT_PUBLIC_APP_NAME - Application name (optional, defaults to KulturalMente)

Vercel Configuration

The project includes optimal settings for Vercel deployment:

Framework Preset: Next.js (auto-detected)
Build Command: npm run build (default)
Output Directory: .next (default)
Install Command: npm install (default)
Node.js Version: 18.x or higher

Post-Deployment Checklist

✅ Verify all environment variables are set correctly
✅ Test the Qloo API integration (search functionality)
✅ Test the OpenAI integration (cultural narrative generation)
✅ Check PDF export functionality
✅ Verify 3D visualization renders properly
✅ Test on mobile devices for responsive design
✅ Configure custom domain (optional)

📄 License

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

🙏 Acknowledgments

Qloo for providing the incredible Taste AI™ API and hosting this hackathon
OpenAI for the powerful language models that make cultural storytelling possible
Next.js team for the amazing React framework
Vercel for seamless deployment capabilities

👨‍💻 Author

Ajito Nelson Lucio da Costa

🌐 Experience KulturalMente: Live Demo

"Your Mind. Your Culture. Your Story." 🧠✨

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
public		public
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
postcss.config.mjs		postcss.config.mjs
tailwind.config.js		tailwind.config.js
test.txt		test.txt
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation