🔗 Persona Matcher

AI-powered professional networking and matching platform

A sophisticated professional networking platform that uses AI-powered text embeddings and graph-based algorithms to connect professionals based on their goals, challenges, skills, and career aspirations.

✨ Key Features

• 🤖 AI-Powered Matching: OpenAI embeddings for semantic similarity and compatibility
• 📊 Graph-Based Algorithms: Skills, interests, industry, and mutual connections
• 🍳 Recipe System: Configurable combinations of matching techniques
• 🌐 Interactive Web Interface: Streamlit-based visualizer with simplified design
• 🔗 GraphQL API: Modern API with type-safe queries
• 🐳 Docker Ready: One-command deployment

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• OpenAI API Key (Get one here)

⚠️ Security Notice: This setup is designed for local development and testing only. The default credentials (neo4j/password) and configuration are not suitable for production use.

One-Command Setup

# Clone the repository
git clone <repository-url>
cd persona-matcher

# Create environment file
cp env.example .env
# Edit .env and add your OpenAI API key: OPENAI_API_KEY=your_key_here

# Start the entire system with data import
./start.sh --import

Other start options:

• ./start.sh - Start without importing data
• ./start.sh --no-build - Start without rebuilding Docker images
• ./start.sh --no-build --import - Start without building + import data

Access Applications

🌐 Match Visualizer (Streamlit)

• URL: http://localhost:8501
• Purpose: Interactive web interface for exploring matches and recommendations
• Features: User selection, recipe-based matching, visual results

🔗 GraphQL API

• URL: http://localhost:8000/graphql
• Purpose: Programmatic access to all system data and matching functions
• Interactive Explorer: Available at the URL above

Example GraphQL Query:

query {
  users(limit: 5) {
    users {
      fullName
      currentTitle
      industry
      yearsExperience
    }
  }
}

Example Matching Query:

query {
  recommendations(userId: "P123456", recipeName: "similar_person", limit: 3) {
    recipeName
    totalMatches
    matches {
      user {
        fullName
        currentTitle
        industry
      }
      score
    }
  }
}

📊 Neo4j Browser

• URL: http://localhost:7474
• Username: neo4j (development only)
• Password: password (development only)
• Purpose: Direct database access for advanced queries and visualization
• Note: These are default development credentials - change for production use

Example Cypher Query:

MATCH (u:User)-[:HAS_SKILL]->(skill)
WHERE skill.name = 'Python'
RETURN u, skill
LIMIT 10

📊 Sample Data

The system includes a pre-loaded dataset of professional personas in export/personas.json. This dataset was generated using the persona-generator tool, which creates diverse, realistic professional profiles using AI models.

Generate Custom Datasets:

# Install persona-generator
pip install persona-generator

# Generate new personas using our schema
persona-generator -s schemas/personas/boardy_persona_schema.yaml -n 100

# Or generate with custom parameters
persona-generator --num-personas 100 --format json --output-dir export

This allows you to create datasets tailored to specific industries, regions, or professional contexts for testing and development.

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Streamlit UI   │    │  FastAPI +      │    │  Neo4j Graph    │
│  (Frontend)     │───▶│  GraphQL API    │───▶│  Database       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │  Matching       │
                       │  Techniques     │
                       │  • AI Embeddings│
                       │  • Graph-Based  │
                       │  • Recipe Engine│
                       └─────────────────┘

🎯 Matching System

AI-Powered Techniques

• Text Similarity: Find people with similar goals and challenges
• Compatibility: Match mentors with mentees based on descriptions

Graph-Based Techniques

• Skills Matching: Similar or complementary skills
• Interests Matching: Shared interests and hobbies
• Industry Matching: Same or related industries
• Mutual Connections: Network-based introductions

Recipe System

Combine multiple techniques with configurable weights for optimal recommendations.

📚 Documentation

📖 Complete System Guide - Comprehensive documentation covering:

• Architecture and design decisions
• Environment setup and configuration
• API documentation and examples
• Development and deployment guides
• Troubleshooting and support

🔍 Graph Database Showcase - Visual queries demonstrating graph database advantages

🚀 System Recommendations - Detailed analysis of:

• Scaling strategies and performance optimizations
• Architectural tradeoffs and design decisions
• Future improvements and enhancement roadmap
• Production readiness considerations

🛠️ Development

Local Development Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start Neo4j
docker-compose up -d neo4j

# Run API
python -m uvicorn app.main:app --reload

# Run Streamlit
cd visualizer && streamlit run match_visualizer.py

Testing

# Run all tests
python -m pytest tests/

# Run specific tests
python tests/run_api_tests.py
python tests/test_comprehensive_matching.py

🔧 Configuration

Environment Variables

Create a .env file with:

# Required
OPENAI_API_KEY=your_openai_api_key_here

# Optional (development defaults)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password
API_HOST=0.0.0.0
API_PORT=8000

🔒 Production Security: For production deployment, change all default passwords, use environment-specific configurations, and follow security best practices for database access and API endpoints.

🚨 Quick Troubleshooting

Services Not Starting?

# Check if all services are running
docker-compose ps

# Restart all services
docker-compose down && docker-compose up -d

# Check logs
docker-compose logs -f

Can't Access Applications?

• Streamlit (8501): Wait 30 seconds after startup, check docker-compose logs streamlit
• GraphQL (8000): Check docker-compose logs api, ensure Neo4j is running first
• Neo4j (7474): Check docker-compose logs neo4j, wait for "Started" message

Missing Data?

# Import sample data (if you have personas.json)
python scripts/import_to_neo4j.py

# Or restart with data import
./start.sh --import

📊 Current Status

• ✅ Core API: FastAPI + GraphQL fully operational
• ✅ AI Embeddings: OpenAI integration working
• ✅ Graph Matching: All techniques implemented
• ✅ Recipe System: Configurable combinations
• ✅ Web Interface: Streamlit visualizer complete
• ✅ Docker: Full containerization
• ✅ Testing: Comprehensive test suite

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

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

🙏 Acknowledgments

• Built with FastAPI and Streamlit
• Powered by Neo4j for graph storage
• AI capabilities via OpenAI embeddings
• Schema-driven design for flexibility and maintainability

---

🎉 Ready to connect professionals through AI-powered matching!

For detailed information, see the Complete System Guide.