Sculptured docs

Team files

Save a team or a group as a file, open it in another Sculptured, and edit it with completion in your editor.

A team file is a whole team in one MADL file: its agents and their Jobs, groups, arrows, workflow and settings. MADL is an open format, so other tools can read the same file. Use it to keep a copy, send a team to a colleague, move it to another Sculptured, or keep it in a Git repository next to the code it works on.

There are three kinds of file:

FileHoldsMade withOpened with
Team file, .madl.yamlA whole teamExport team file under Export in the team's SettingsNew project → Advanced: import a team file or a past run → Import
Group file, .group.jsonOne reusable groupExport on a group in Reusable groupsImport group file in Reusable groups
Run file, .sculptured-session.jsonlOne past run: the team as it started, then every eventDownload run in Results › HistoryNew project → Advanced: import a team file or a past run → Import a past run
flowchart LR
  T["Team on the board"] -- "Export team file" --> F[".madl.yaml"]
  F -- "Import" --> T2["New team in any Sculptured"]
  G["Group in Reusable groups"] -- "Export" --> GF[".group.json"]
  GF -- "Import group file" --> G2["Group, reviewed then saved"]
  GF -- "Publish" --> C["Community"]
  R["A finished run"] -- "Download run" --> RF[".sculptured-session.jsonl"]
  RF -- "Import a past run" --> H["Read-only run in History"]

Export a team

  1. Open the team
    Open the project.
  2. Open Settings
    Open its Settings tab and find Export.
  3. Choose about folders
    Leave Include folders (paths on this computer) off to share the file. Folders are paths on one computer, so they rarely make sense anywhere else. Turn it on to keep a backup for the same computer.
  4. Export
    Choose Export team file. The file goes to your downloads as <team>.madl.yaml.

The same section has View as spec, which shows the team as text without saving a file.

Import a team

  1. Start a new project
    Open New project.
  2. Open Advanced
    Open Advanced: import a team file or a past run at the bottom of the page.
  3. Choose the file
    Choose the file, or paste its contents into the box. A MADL file (.madl.yaml or .madl.json), an older .sculptured-team.json file and an OpenRig YAML file are all accepted.
  4. Import
    Choose Import. A new team is created, with a new id made from its name.
  5. Fix what the board lists
    Set a folder and fix anything listed under things to fix before you start the team.

What import does with a file:

Importing the same file twice makes two teams. Retrying a request that did not answer does not.

Export and import a group

A group is a reusable part of a team, such as a builder and a reviewer. Groups live in Library → Reusable groups.

Group files are cleaned on export and on import, the same way Community cleans a block before publishing. Folders, model choices and the workflow's Input are removed. Every agent is set to Restricted and to start a fresh session. See Community.

Edit a team file by hand

A team file is YAML you can read and edit. Its JSON form (.madl.json) starts with a $schema line naming MADL's JSON Schema, so editors that understand JSON Schema check the file and complete field names as you type; VS Code does this with no setup. For YAML, the YAML extension reads the same schema.

The madl command checks a file before you import it:

cargo install --git https://github.com/Sculptured/Multi-Agent-Descriptor-Language madl-cli
madl validate my-team.madl.yaml

Every field is described in MADL's specification; MADL files lists where each part of a Sculptured team goes.

Keep a team in Git

A team file without folders is the same on every computer, so it fits in a repository:

  1. Export the team without folders.
  2. Commit the file, for example as team/review-loop.madl.yaml.
  3. Review changes to Jobs in pull requests like any other text.
  4. To use a new version, import it as a new project. Import never overwrites a team you already have.

Share a past run

A run file lets someone see exactly what happened in a run without running anything. It holds the team as it started and every recorded event in order.

  1. Open the run in History and choose Download run.
  2. Send the .sculptured-session.jsonl file.
  3. The other person imports it with Import a past run. It opens in History, read-only, labelled as imported from a file.

Next steps