MLStudio Documentation

On This Page

Overview

MLStudio (technical package name Beep.Python.MLStudio) is a Flask-based web application that makes machine learning project work more repeatable and accessible. It combines project management, experiment orchestration, visual workflow templates, dataset handling, and industry-focused guidance into a single browser UI, and it connects into the wider Beep platform ecosystem.

The platform is designed for two main audiences:

• Users who want to create and manage ML projects through guided UI flows — projects, datasets, experiments, and workflows.
• Developers who need to extend routes, services, workflows, integrations, and templates.

MLStudio ships with in-app help surfaces (documentation hub, tutorials, and FAQ) served directly from the running application, so guidance stays close to the tasks it describes.

Core Capabilities

Quick Start

The recommended path is a single command. You do not need to manually create environments, install packages, or initialize the database — the launcher handles first-run setup for you. Only switch to direct execution once the environment and configuration are already stable.

run.bat

./run.sh

python run_mlstudio.py

On macOS you can also double-click run.command from Finder.

First-Run Behavior

The launcher performs setup automatically, in order:

1. Check Python compatibility (Python 3.8+)
2. Create the working virtual environment (.venv) when missing
3. Install Python dependencies from requirements.txt
4. Set up the local bootstrap Python runtime when required
5. Create or repair the environment configuration (.env)
6. Create required working directories (for example data/ and projects/)
7. Initialize the database (mlstudio.db)
8. Start the Flask app and open it in a browser

The default local application URL is http://127.0.0.1:5001.

Architecture

MLStudio uses an application-factory-based Flask architecture. Route blueprints, service modules, model definitions, template views, and static assets are separated by responsibility, so behavior is added through targeted modules rather than large monolithic handlers.

Registered route groups include dashboard, projects, experiments, models, settings, industry, documentation, tutorials, faq, competitions, profile, admin, auth, setup, ml_server, and the versioned API blueprint mounted under /api/v1.

Source Layout

User Guide

The fastest path is to run a launcher script, let the app finish first-run setup, then create a project that acts as the container for your datasets, experiments, notebooks, and workflows.

Creating Your First Project

1. Open Projects in the navigation menu.
2. Click Create New Project.
3. Enter a project name and description.
4. Select your preferred ML framework (for example TensorFlow, PyTorch, or Scikit-learn).
5. Click Create to initialize the project.

Understanding the Interface

• Dashboard: overview of your projects and recent activity
• Projects: manage and organize your ML projects
• Experiments: run and compare different model configurations
• Workflows: visual workflow builder for pipelines
• Industry: scenario and vertical-specific guidance
• Documentation: in-app user, API, workflow, and developer references

Core Concepts

• Projects are the primary working container — keep related datasets, notebooks, experiments, and workflow definitions grouped by problem or use case.
• Experiments represent a single run with specific parameters, data, and configuration, letting you test hyperparameters, compare performance, track metrics, and reproduce results.
• Workflows are visual, repeatable pipelines that standardize data preparation, model steps, evaluation, and scenario-specific logic.

Data Management

MLStudio supports common data formats: CSV, JSON, Parquet, Excel (.xlsx, .xls), and image formats such as JPG and PNG. To add data, open a project, click Upload Dataset, select the file, configure schema and preprocessing options, then upload. Validate datasets early and keep naming consistent so the right workflow or experiment can use them.

Running Experiments

1. Open a project and click New Experiment.
2. Select a dataset and choose a model algorithm.
3. Configure hyperparameters and click Run.
4. Monitor loss curves, accuracy metrics, progress, resource usage, and experiment-specific logs and output artifacts.

Workflow Authoring & Templates

Workflows are visual representations of ML pipelines, made of nodes connected by edges. To build one: open a project, click New Workflow, add nodes from the node library, connect output ports to input ports, configure each node's parameters, then save and run.

Node Types

• Data Nodes: load data from files, databases, or APIs
• Preprocessing Nodes: clean, transform, and prepare data
• Model Nodes: train machine learning models
• Evaluation Nodes: assess model performance
• Output Nodes: save results and deploy models

Workflow Templates

Pre-built templates cover common use cases: classification pipelines, regression workflows, time-series forecasting, image classification, and industry-specific templates. Reusable definitions live under workflow_templates/.

Advanced Workflows

• Conditional branching
• Loops and iterations
• Custom Python nodes
• Parallel processing
• External API integration

Industry Guides & Scenarios

MLStudio provides industry modes that bring specialized workflows and terminology. Switch to an industry mode to access its templates and scenarios.

Additional vertical-oriented scenario seeds (for example marine scenarios) are provided as seeding scripts so example content can be loaded and adapted to your own projects.

API Surface

REST endpoints are served by the API blueprint mounted under /api/v1 (dataset routes are also exposed under /api to match the frontend). The exact route set is defined by the modules registered in the API package. Real endpoint areas include:

Example: Projects

GET /api/v1/projects

Returns a JSON payload of the project resources for the current context:

{
  "success": true,
  "projects": [
    {
      "id": 1,
      "name": "My Project",
      "description": "Project description",
      "framework": "tensorflow",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

POST /api/v1/projects

{
  "name": "New Project",
  "description": "Project description",
  "framework": "pytorch"
}

Authentication & Errors

Authentication requirements depend on the deployed route set and configuration. Protected routes accept a bearer token or session-backed credentials. Responses generally follow a consistent JSON shape (success, data, optional message), and standard HTTP status codes apply — 400 bad request, 401 unauthorized, 403 forbidden, 404 not found, and 500 internal server error. Consult the in-app API reference at /documentation/api-reference for live guidance.

Configuration

The launcher creates a local environment configuration when needed. Typical settings include:

SECRET_KEY=change-me
DEBUG=true
HOST=127.0.0.1
PORT=5001
DATABASE_URL=sqlite:///mlstudio.db
MAX_UPLOAD_SIZE=100
UPLOAD_FOLDER=data
PROJECTS_FOLDER=projects

Use config/mlstudio_config.json and the settings guide as the authoritative references for supported settings and application behavior. To run on a different port, change PORT in the .env file (for example to 5002).

Dependencies

MLStudio targets Python 3.8+ and is licensed under the MIT License. The following packages are declared in requirements.txt:

Heavier or optional integrations — such as MLflow, ChromaDB, Pinecone, sentence-transformers, TensorFlow, and PyTorch — are intentionally kept out of the default bootstrap and are installed on demand into project-specific virtual environments (via Beep.Python.Host.Admin) or by workflow/node package management, so the base app avoids pulling large transitive stacks.

Developer Guide

Use the standard launcher first so you work inside the same startup path as normal users. Only switch to direct execution once the environment and configuration are stable. Useful entry points include run_mlstudio.py, run.py, wsgi.py, and init_db.py.

How to Extend the Application

1. Find the nearest existing route package for the feature area, and put request handling there.
2. Put business rules in services, not in view functions.
3. Add or update models only when the data contract changes.
4. Keep templates focused on rendering, not business logic.
5. Adjust API routes separately from browser templates when the contract differs.
6. Update in-app help and README content when behavior changes.

Extension Points

• Documentation / tutorials / FAQ: route packages under app/routes/documentation, app/routes/tutorials, and app/routes/faq, backed by the help content service.
• Workflows: reusable definitions under workflow_templates/, seeding scripts under scripts/, and API-side handling in the workflow route modules.
• Integrations: the app already contains surfaces for Host Admin, ML server, community publishing, workflow APIs, and webhooks — check whether an existing route group or service already owns a concern before adding a new one.

Troubleshooting

Application Does Not Start

• Verify Python 3.8+ is installed and on your PATH.
• Run the standard launcher rather than invoking internal modules directly.
• Confirm the bootstrap/embedded Python setup completed on first run.
• Review startup_output.txt and startup_error.txt when present.

Environment or Dependency Problems

• Re-run the launcher so the environment setup path can self-repair.
• Verify requirements.txt is present and readable.
• If first-run bootstrap fails, run setup_embedded_python.bat (Windows) or ./setup_embedded_python.sh (Linux/macOS). The bootstrap runtime creates .venv; MLStudio itself runs from .venv afterward.

Port Already in Use

• Change PORT in .env to a free port (for example 5002), or stop the process currently using port 5001.

Database Issues

• Review init_db.py and check_db.py.
• Confirm the configured DATABASE_URL is valid.
• Use the generated setup and debug output files to trace startup behavior.

Help or Documentation Looks Incomplete

• Check the documentation routes under /documentation.
• Verify help content exists and template files under templates/documentation, templates/tutorials, and templates/faq match the expected route behavior.