Skip to main content
Glama
research-workflow-studio

research-workflow-studio

by BorgDiven
README.md
<p align="center">
  <img src="docs/assets/research-workflow-studio.png" alt="Research Workflow Studio — questions, implementations and evidence connected in a human-guided loop" width="100%">
</p>

# Research Workflow Studio

**A visual, human-guided research workflow — from questions to reusable code, evidence and reports.**

[Website & interactive demo](https://borgdiven.github.io/research-workflow-studio/) · [English website](https://borgdiven.github.io/research-workflow-studio/en/) · [简体中文](README.zh-CN.md) · [Quick start](#quick-start) · [MCP](#connect-your-ai-client)

Research rarely follows a straight line. You explore a question, inspect intermediate outputs, reuse a control, change a method and compare again. Research Workflow Studio keeps those relationships visible without treating every case as a new code version or every result as a new research claim.

It is a **local desktop web workbench with a Python backend, SQLite storage and an MCP server**. An AI client can create and read structured records through MCP; an explicitly invoked command-line executor can run reviewed Git and task requests. You decide the research direction, conclusions and project-level changes.

## One workspace, three views

| View | What it helps you do |
| --- | --- |
| **Research** | Read the project foundation, follow branching questions and hypotheses, see the current stage and reuse evidence. Exploration does not require an improvement hypothesis. |
| **Code & execution** | Define inputs and outputs before implementation; follow training, inference, evaluation, analysis and report code separately. Inspect actual execution provenance when needed. |
| **Outputs & comparison** | Use image grids, compatible curve overlays or scoped metric tables. Freeze selected process data before reusing it in an analysis or report; missing values stay missing. |

Saved comparisons are working selections. Analyses explain observations and their limits. Reports preserve the exact evidence and project context used at the time; new results do not rewrite old reports.

The walkthrough and desktop previews below show the 0.3 interface and use a separate fictional project with generated geometric shapes and manually specified example metrics. No private research data or model execution is involved.

[Watch the project-to-workspace walkthrough](https://github.com/BorgDiven/research-workflow-studio/releases/download/v0.3.3/workspace-tour.mp4)

![Project home, research, code selection and output comparison](docs/assets/workspace-tour.gif)

**Research**
![Research tree with project foundation](docs/assets/research-view.png)

**Code & execution**
![Code roles and reusable implementations](docs/assets/code-view.png)

**Outputs & comparison**
![Evidence comparison](docs/assets/comparison-view.png)

## Quick start

Requires **Python 3.9+**. Runtime has no third-party Python or JavaScript dependencies. The UI is designed for desktop browsers; interface text is currently Chinese.

```sh
git clone https://github.com/BorgDiven/research-workflow-studio.git
cd research-workflow-studio
mkdir -p .local
python3 tools/seed_showcase.py --db "$PWD/.local/showcase.sqlite3"
python3 launch.py serve --db "$PWD/.local/showcase.sqlite3" --port 8831
```

Open **http://127.0.0.1:8831**. The showcase includes a project home, branching research questions, code roles, geometric illustrations, curves and fixed reports. Seeding is repeatable and refuses databases containing unrelated projects. It does not run a model or measure image quality.

For your own empty workspace, choose a different database path and skip the seed command:

```sh
python3 launch.py serve --db "$PWD/.local/my-research.sqlite3" --port 8831
```

Optional CLI installation in your Python virtual environment from this checkout: `python3 -m pip install .`, then `research-workflow-studio serve --db /absolute/path/studio.sqlite3`. Source-based development templates remain in this repository.

## Connect your AI client

MCP is the structured tool interface between an AI client and Studio. Configure a **stdio MCP server** using your actual absolute paths:

```json
{
  "mcpServers": {
    "research-workflow-studio": {
      "command": "python3",
      "args": [
        "/absolute/path/research-workflow-studio/launch.py", "mcp",
        "--db", "/absolute/path/studio.sqlite3",
        "--web-url", "http://127.0.0.1:8831"
      ]
    }
  }
}
```

The browser service and MCP process must use **the same database**. Adapt the configuration wrapper to your client, reconnect it and inspect its loaded tools. MCP configuration alone does not start the web server.

A useful first prompt:

> Open my project in Research Workflow Studio. Read its foundation and current research context. Tell me what is already recorded, what is missing and the next useful action. Before implementing a method, find reusable code and agree on a specification. Do not execute an experiment or approve a scientific decision without my instruction.

The 37 advertised MCP tools let the model read context, manage research records, append/query process metrics, freeze evidence, register repositories/environments and propose concrete Git or task requests. Mutations such as starting or stopping a task, committing or pushing require a separate human confirmation. Read-only inspections can be claimed directly by the explicit CLI executor. Neither MCP registration nor approval executes a command; there is no arbitrary-shell or arbitrary-file-read MCP tool. See [the current tool schemas](web/docs/tools.json) and [the 0.4 contract](docs/contract-v4.md).

**Inspect code without losing the research context.** Related-code navigation highlights exact implementations and specifications. Details stay in the right column; cancelling highlights preserves the research context and current code selection.

![0.4.2 persistent research associations and right-side details in a fictional project](docs/assets/research-code-highlight.png)

## Track training without turning every step into a card

![0.4 process tracking with fictional training observations](docs/assets/process-tracking.png)

Declare a process metric on the code specification, then batch its observations from your script. The workbench preserves metric identity, units, axis, data scope and the exact protocol/specification. Incompatible or unknown scopes stay separate; gaps are not zeroes. Switch between images, curves and metrics in the same output view.

Use `tools/track_metrics.py` for JSONL input or an explicitly selected MLflow HTTP history. Its local spool supports retries. MLflow import reads run-scoped metrics only; supply declared splits with `--mlflow-split` and use JSONL for explicit per-sample data. It does not install, discover, control or take over an MLflow service. Save a fixed metric-history artifact before using process data in a comparison, analysis or report. [Usage and formats](docs/usage-guide.md)

## Review work, then execute it

Open **仓库与运行环境** (Repositories & environments) in the project. Register an existing local checkout or SSH alias, and pin the repository/environment on a run. Request a Git action or task, review its exact arguments, then copy the generated executor command to the Studio host's terminal:

```sh
python3 launch.py operate --db /absolute/path/studio.sqlite3 \
  --project-id example-project --operation-id operation-example --version 2
```

The identifiers above are fictional placeholders. Use the exact revision shown by your real request. This is an execution command, not a preview. The runner claims one request, checks the fixed source commit and records its receipt. Unknown launch outcomes are not retried automatically. Remote SSH behavior has been checked with mocked transport; a real server still needs its own explicit integration check. Execution and tracking clients target POSIX systems such as macOS/Linux.

## Build reusable research blocks

```sh
python3 tools/scaffold.py --kind inference --destination .local/my-method --title "My method"
python3 tools/check_block.py .local/my-method --output .local/check.json
```

The checker is static by default. Add `--execute` only when you intend to execute that block locally. The supplied templates use small standard-library synthetic fixtures, with no model downloads or GPU usage.

A specification declares purpose, input/output semantics, configurable values, dependencies and acceptance checks. A registered implementation pins a ready specification revision, repository, Git commit, module path, entrypoint and supplied check evidence. Cases and ordinary parameter changes belong in inputs/configuration. See [the five templates](templates/README.md) and [contributor rules](AGENTS.md).

## Data that stays understandable

- **Question ≠ implementation lineage.** A baseline can support several questions without changing its origin.
- **Declare purpose before running.** Link a question to a code specification or existing implementation, then navigate both ways. Planned purpose, actual use and reused evidence remain distinguishable; see [the relationship contract](docs/contract-v3.md#declare-which-research-the-implementation-serves).
- **Artifact origin stays fixed.** Reusing an image in another experiment or project adds a reference, not a new producer.
- **An execution may cover several cases or settings.** Each artifact carries its actual configuration and output semantics. Execution details are available without another visible grouping layer.
- **Final output ≠ diagnostic output.** A predicted clean image, velocity field, curve and metric table can be compared as the corresponding kind of evidence.
- **Corrections are audited.** Approved amendments preserve the original record; previously frozen reports retain their original snapshot.
- **A completed run ≠ a supported hypothesis.** Scientific judgments and project-foundation changes remain human decisions.

## Lighter reading, protected originals

Comparisons and enlarged images use a separate reading copy. Managed PDF reports open a reading edition, while original downloads stay inside material details. The local cache has a configurable size limit; originals and fixed evidence are never eviction targets. You can keep everything locally or put originals on a separate volume without changing material links.

Image conversion is optional: install `.[previews]`; add `.[pdf-readings]` for reading PDFs. Missing converters show unavailable reading content instead of silently downloading originals. See [storage, retention and reading copies](docs/storage-and-reading.md).

## Private remote use

The service binds to loopback. It supports an explicitly configured **Tailscale Serve** proxy for private cross-device use; see [deployment](docs/deployment.md). Real projects, SQLite files and managed materials stay on your server. This public repository contains software and synthetic examples, not a public hosted workspace.

## Development and status

Version **0.5.1** is an early, single-user workbench. It has no collaborative multi-user permissions, cloud synchronization, automatic experiment scheduler or mobile layout. Supplied check evidence is recorded, not independently certified. Review changes and keep a database backup when upgrading.

```sh
python3 -m unittest discover -s tests
node --test web/tests/*.test.js
```

See [usage](docs/usage-guide.md), [data formats](docs/format-guide.md), [changes](CHANGELOG.md), [architecture](docs/architecture.md) and [contributing](CONTRIBUTING.md). Issues describing a concrete workflow are welcome.

MIT licensed. The title illustration and demo contact sheet are AI-generated branding/illustration assets, not experimental evidence; [asset provenance](docs/assets/banner-prompt.md).

TDQS

C2.8/5.0

Scored across 37 tools

Disambiguation4/5

Most tools target a distinct entity or lifecycle action, and the descriptions clarify boundaries between registration, querying, proposal, and human-only approval. There is still some potential confusion among the many save/register/propose variants and the three propose/apply/dismiss triads, but the domain objects remain distinguishable.

Naming Consistency4/5

The naming is overwhelmingly consistent: an rws_ prefix plus snake_case entity/action names such as rws_project_create and rws_run_register. A few outliers like rws_get_context, rws_report_create_revision, and rws_project_stages_set break the dominant noun_verb pattern but remain readable.

Tool Count2/5

37 tools is heavy for an MCP surface, even for a broad research lifecycle. Several lifecycle stages are fragmented into multiple tools, especially the propose/apply/dismiss triads, and consolidation would reduce the surface without losing core capability.

Completeness4/5

The surface covers a wide research workflow: project setup, records, code, runs, artifacts, datasets, evaluations, reports, metrics, proposals, and human approvals. Minor gaps remain around explicit retrieval or listing for some entity types, but generic record access and query tools mitigate most dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues