Projects

+ New page

Plan: Product vision & feature set

• Date: 2026-08-16
• Author:
• Status: Draft
• Related project: ../projects/hutfx.md

Goal

A written description of the functionalities and services hutfx will provide, and the order in which we build them — agreed with the owner before any feature code is written.

At a glance

How the proposed pieces fit together. (Any fenced code block with the mermaid info string in a doc file is drawn as a diagram.)

Background

The foundation (auth, dashboard, profile, landing page, /doc) is done. The product itself — a workspace for machine learning and science — is not yet specified. This document is the first draft of that specification.

Proposed functionalities & services

Everything below is a proposal. Mark each area ✅ keep / ✏️ change / ❌ drop before we start building.

1. Experiments (core)

Structured record of ML runs inside a project:

• Create a project (name, description, tags)
• Log a run: name, start/end, parameters (key-value), metrics (key-value), notes
• List / filter / sort runs in a table; run detail page with notes
• Compare two runs side-by-side (metrics diff)

2. Datasets

• Upload a dataset (CSV / Parquet first?), name + description
• Dataset versions (re-upload creates a new version)
• Link a run to the dataset (and version) it used
• List page with size, version count, last-used date

3. Artifacts / files

• Attach files to a run: plots (PNG), checkpoints, logs, anything
• Stored on local disk, metadata in PostgreSQL, streamed back for download
• Image preview for plots on the run detail page

4. Jobs

• Enqueue a job (script + arguments) that runs on the server
• Queue with status: queued → running → succeeded / failed
• Live log tail per job
• A job can produce a run (automatic link)

5. Model registry

• Register a model (name, framework, size) with versions
• Each version links to the run (and dataset) that produced it
• Compare versions; mark one as "current"
• Download the model file

6. Public API (for external programs)

• Personal access tokens per user
• REST endpoints: create run, log param/metric, upload artifact, enqueue job
• API reference published under /doc

7. Workspace UX

• Dashboard home: recent runs / datasets / jobs + quick actions
• Search across projects, runs, and models
• Strict per-user data isolation (single-user for now)

Proposed build order

1. Experiments MVP — smallest useful product, no files or compute yet
2. Datasets + artifacts
3. Jobs (needs the compute-location decision first)
4. Model registry
5. Public API

The milestone table lives in ../projects/hutfx.md.

Risks / Open questions

• Who is the user? Individual researcher (single-user) or teams? This affects data isolation, permissions, and the whole data model.
• Where does compute run? Does hutfx execute training jobs on its own server (milestone 3), or is it a tracking/workspace tool and training runs elsewhere (notebooks, laptops, a cluster)?
• File sizes? Checkpoints can be gigabytes — local disk + PostgreSQL is fine for small files; large artifacts may need S3-compatible storage later.
• Language bindings? Is a Python client (report runs from notebooks/scripts) part of the vision, or a plain REST API?
• Open source or private product? Affects licensing, branding, and how public the /doc site should be.
• Data format priorities? Which dataset formats matter first (CSV, Parquet, HDF5, images)?

Steps

• [ ] 1. Owner reviews each proposed area (keep / change / drop) and answers the open questions
• [ ] 2. Update this file + ../projects/hutfx.md scope & milestones with the confirmed set
• [ ] 3. Write a dedicated plan file per milestone (starting with Experiments MVP)
• [ ] 4. Build milestone by milestone; keep milestone status updated in the project file

Result

(Draft — awaiting owner review.)