amit78kum/pysr-mcp-server-amit

🔬 PySR Symbolic Regression Platform

A complete end-to-end platform for symbolic regression using PySR with MCP server architecture, FastAPI backend, PostgreSQL database, and beautiful Streamlit UI.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    STREAMLIT UI (Frontend)                   │
│  • Login/Authentication                                      │
│  • Dashboard with job management                             │
│  • Job submission with sliders & operator selection          │
│  • Results visualization & metrics                           │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTP/REST API
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              FastAPI APP SERVER (Backend)                    │
│  • Authentication (JWT)                                      │
│  • Job management & file upload                              │
│  • Database operations (PostgreSQL)                          │
│  • MCP Client integration                                    │
└────────────────────┬────────────────────────────────────────┘
                     │ MCP Protocol (stdio)
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              PySR MCP SERVER                                 │
│  • Symbolic regression engine                                │
│  • Data validation & preprocessing                           │
│  • Model training & evaluation                               │
│  • Equation discovery & export                               │
└─────────────────────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              PostgreSQL DATABASE                             │
│  • Users (authentication)                                    │
│  • Jobs (job metadata)                                       │
│  • Job Runs (execution details)                              │
│  • File Storage (uploaded datasets)                          │
└─────────────────────────────────────────────────────────────┘

🚀 Features

PySR MCP Server

• ✅ Complete training pipeline with single endpoint
• ✅ 11 comprehensive tools for model operations
• ✅ Automatic data validation
• ✅ Real-time training monitoring
• ✅ Multiple equation export formats (LaTeX, SymPy, JAX, PyTorch)
• ✅ Model persistence (save/load)

FastAPI Backend

• ✅ JWT-based authentication
• ✅ RESTful API design
• ✅ PostgreSQL database integration
• ✅ File upload management
• ✅ Job queue and status tracking
• ✅ MCP client integration via stdio

Streamlit UI

• ✅ Beautiful gradient-based design
• ✅ User authentication (login/register)
• ✅ Interactive job dashboard
• ✅ Parameter configuration with sliders
• ✅ Operator selection with checkboxes
• ✅ Real-time job status monitoring
• ✅ Rich results visualization
• ✅ Plotly-based interactive charts

📦 Installation

Prerequisites

• Python 3.8+
• PostgreSQL 12+
• Julia (for PySR)

Step 1: Install Julia

# Download and install Julia from https://julialang.org/downloads/
# Add Julia to your PATH

Step 2: Clone Repository

git clone <your-repo-url>
cd pysr-platform

Step 3: Create Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 4: Install Dependencies

pip install -r requirements.txt

Step 5: Install PySR Julia Backend

python -c "import pysr; pysr.install()"

Step 6: Setup PostgreSQL Database

Using Docker (Recommended)

docker run --name pysr-postgres \
  -e POSTGRES_USER=pysr_user \
  -e POSTGRES_PASSWORD=pysr_pass \
  -e POSTGRES_DB=pysr_db \
  -p 5432:5432 \
  -d postgres:15

Manual Setup

# Create database and user
psql -U postgres
CREATE DATABASE pysr_db;
CREATE USER pysr_user WITH PASSWORD 'pysr_pass';
GRANT ALL PRIVILEGES ON DATABASE pysr_db TO pysr_user;

Step 7: Environment Configuration

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

Step 8: Initialize Database

The database tables will be created automatically when you first run the app server.

🎯 Running the Application

Terminal 1: Start FastAPI Backend

python app_server.py

Backend will run on: http://localhost:8000

Terminal 2: Start Streamlit UI

streamlit run streamlit_app.py

UI will open in browser: http://localhost:8501

📖 Usage Guide

1. Register/Login

• Open the Streamlit UI in your browser
• Click "Register" to create a new account
• Or login with existing credentials

2. Create New Job

1. Click "🆕 New Job" in the sidebar

2. Upload your CSV dataset

3. Select target column and features

4. Configure training parameters using sliders:

   • Iterations: Number of training iterations (10-100)
   • Populations: Number of populations (5-30)
   • Population Size: Size of each population (10-50)
   • Max Complexity: Maximum equation complexity (10-50)
   • Parsimony: Penalty for complexity (0.0-0.01)

5. Select operators using checkboxes:

   • Binary: +, -, *, /, ^
   • Unary: sin, cos, exp, log, sqrt, abs

6. Click "🚀 Submit Job"

3. Monitor Jobs

• View all jobs in the dashboard
• Check job status (Pending/Running/Completed/Failed)
• Click "👁️ View" to see detailed results

4. View Results

For completed jobs, you'll see:

• Best Equation: In LaTeX and SymPy formats
• Performance Metrics: R², RMSE, MSE, MAE
• Top Equations: List of discovered equations
• Visualizations:
  • Predictions vs Actual line plot
  • Scatter plot with trend line

📊 Sample Dataset

Create a sample dataset for testing:

import numpy as np
import pandas as pd

# Generate synthetic data
np.random.seed(42)
X = np.random.uniform(-3, 3, 100)
y = 2.5 * X**2 - 3.1 * X + 1.5 + np.random.normal(0, 0.5, 100)

# Create DataFrame
df = pd.DataFrame({
    'x': X,
    'y': y
})

# Save to CSV
df.to_csv('sample_data.csv', index=False)

This dataset represents the equation: y = 2.5x² - 3.1x + 1.5

You can also download sample datasets from:

• UCI Machine Learning Repository
• Kaggle Datasets

🔧 API Endpoints

Authentication

• POST /auth/register - Register new user
• POST /auth/login - Login user
• GET /auth/me - Get current user info

File Management

• POST /upload - Upload dataset file

Job Management

• POST /jobs/submit - Submit new job
• GET /jobs - List all user jobs
• GET /jobs/{job_id} - Get job details
• DELETE /jobs/{job_id} - Delete job
• GET /jobs/{job_id}/status - Get job status

🧪 MCP Server Tools

The PySR MCP server provides these tools:

1. train_model_complete - Single endpoint for complete training pipeline
2. create_model - Create model with configuration
3. fit_model - Fit model on data
4. predict - Make predictions
5. get_equations - Get discovered equations
6. save_model - Save model to disk
7. load_model - Load model from disk
8. export_equation - Export in various formats
9. validate_data - Validate input data
10. evaluate_model - Evaluate model performance

🗃️ Database Schema

Users

- id (PK)
- username (unique)
- email (unique)
- password_hash
- created_at

Jobs

- id (PK)
- user_id (FK)
- run_id (unique)
- created_date
- completed_date
- status
- config (JSON)
- location

Job Runs

- id (PK)
- job_id (FK)
- status
- started_at
- completed_at
- results (JSON)
- error_message

File Storage

- id (PK)
- user_id (FK)
- job_id (FK)
- file_path
- file_type
- created_at

🎨 UI Features

• Gradient Design: Beautiful purple gradient theme
• Responsive Layout: Works on desktop and tablet
• Interactive Elements: Sliders, checkboxes, buttons
• Real-time Updates: Auto-refresh job status
• Data Visualization: Plotly interactive charts
• Status Badges: Color-coded job statuses
• Metric Cards: Attractive metric displays

🔐 Security Features

• JWT-based authentication
• Password hashing with bcrypt
• Token expiration
• User-specific data isolation
• Secure file upload handling

🐛 Troubleshooting

Julia Not Found

export PATH="$PATH:/path/to/julia/bin"

PostgreSQL Connection Error

• Verify PostgreSQL is running
• Check credentials in .env file
• Ensure database exists

MCP Server Communication Error

• Ensure mcp_server.py is in the same directory
• Check Python path in app_server.py

Port Already in Use

# For FastAPI (port 8000)
lsof -ti:8000 | xargs kill -9

# For Streamlit (port 8501)
lsof -ti:8501 | xargs kill -9

📝 Development

Project Structure

pysr-platform/
├── mcp_server.py          # PySR MCP Server
├── app_server.py          # FastAPI Backend
├── streamlit_app.py       # Streamlit UI
├── requirements.txt       # Python dependencies
├── .env.example          # Environment template
├── README.md             # This file
├── uploads/              # User uploaded files
└── models/               # Saved models

Adding New Features

1. New MCP Tool: Add to mcp_server.py list_tools() and implement handler
2. New API Endpoint: Add route to app_server.py
3. New UI Page: Add page function in streamlit_app.py

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• PySR - Symbolic Regression library
• FastAPI - Modern web framework
• Streamlit - Data app framework
• MCP - Model Context Protocol

📞 Support

For issues and questions:

• Open an issue on GitHub
• Check documentation at PySR Docs

Made with ❤️ for the symbolic regression community