Schema: define basic schema for workflow

[psschwei]

As a user, I want a defined schema to write my beehive workflow in.

This is related with #47 and #48

[psschwei]

Working draft of a workflow

apiVersion: beehive/v1
kind: Workflow
metadata:
  name: beehive-deployment
  labels:
    app: mas-example
spec:
  strategy:
    type: sequence
    output: verbose
  template:
    metadata:
      labels:
        app: mas-example
    agents:
      - name: agent1
      - name: agent2
      - name: agent3
    prompt: Here is where I would put the prompt I would give to my multi-agent workflow

[maximilien]

Did you upload the example workflow that you presented in demo @psschwei?

Also similar question @developer-gliu?

I want to ensure schema matches. ideally we should have these in a demo or use-case directory. LMK

[george-lhj]

Yup, I have it in a branch currently. I don't exactly have a demo folder, but I just followed pauls current structure.
The hierarchy is the examples -> pauls example folder / my example folder -> code

LMK on the schema you settle and I can edit to match it

[psschwei]

Did you upload the example workflow that you presented in demo @psschwei?

Yes, it's in a top-level examples directory, though that may change as there's some discussion about having separate examples directories for each subproject rather than a single one for all

[maximilien]

OK folks, so for the schema I did some research and the best approach is to use JSON schema. Since YAML can be converted to JSON (and vice versa) then the same JSON schema can be used to validate the YAML. This is my first attempt:

Proposed schema for the current agreed upon workflow — does not include conditional since we need to agree on that; see my comment in PR #124

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/i-am-bee/bee-hive/workflow.schema.json",
  "title": "Bee Hive",
  "description": "A schema for defining Bee Hive workflows in YAML or JSON",
  "type": "object",
  "properties": {
    "apiVersion": "string",
    "kind": "string",
    "metadata": {
      "name": "string",
      "labels": "object"
    },
    "spec": {
      "strategy": {
        "type": "sequence"
      },
      "template": {
        "metadata": {
          "name": "string",
          "labels": "object"
        }
      }
    },
    "agents": [],
    "exception": "string",
    "steps": []
  }
}

A valid JSON and YAML for this schema follows:

{
  "apiVersion": "beehive/v1",
  "kind": "Workflow",
  "metadata": {
    "name": "beehive-deployment",
    "labels": {
      "app": "example2"
    }
  },
  "spec":{
    "strategy": {
      "type": "sequence"
    },
    "template": {
      "metadata": {
        "name": "beehive-deployment",
        "labels": {
          "app": "example",
          "use-case": "test"
        }
      }
    },  
    "agents": [
        "agent1",
        "agent2",
        "agent3"
    ],
    "exception": "step4",
    "steps": [
       "step1",
       "step2",
       "step3",
       "step4"
    ],
    "step1": {
       "agent": "agent1"
    },
    "step2": {
       "agent": "agent2"
    },
    "step3": {
       "agent": "agent1"
    },
    "step4": {
       "agent": "agent3"
    }
  }
}

---
apiVersion: beehive/v1
kind: Workflow
metadata:
  name: beehive-deployment
  labels:
    app: example2
spec:
  strategy:
    type: sequence
  template:
    metadata:
      name: beehive-deployment
      labels:
        app: example
        use-case: test
  agents:
  - agent1
  - agent2
  - agent3
  exception: step4
  steps:
  - step1
  - step2
  - step3
  - step4
  step1:
    agent: agent1
  step2:
    agent: agent2
  step3:
    agent: agent1
  step4:
    agent: agent3

Please comment directly here. I will submit my PR that uses this schema and the two tests workflows for this issue. Finally, since we will need various iterations as we evolve the workflow language and schema, I will open a similar issue for each iterations.

CC: @psschwei @akihikokuroda @planetf1

[george-lhj]

Just to prevent possible issues, for the exception field in the original schema definition, would it make sense to enforce that the string actually is part of steps also? Otherwise, as long the input is a string, then it would be valid declaration which could cause an error.

The rest of the schema make sense to me

[planetf1]

• Can we add a version to the workflow spec ie maybe it's https://github.com/i-am-bee/bee-hive/workflow.schema-v1.0.json. Perhaps also add a specVersion`parameter (both of these are how CycloneDX seems to do it - but there are many ways...)
• I think it's fine the schema evolves changes in a breaking way in our first few iterations - we're still learning a lot.
• We only have steps, and have a sequence strategy. in future I think we need the ability to mix parallel/sequential for more complex flows. At a minimum a two level hierarchy (tasks/steps for example). but as per previous comment we can omit for now.

[psschwei]

I commented in Aki's PR, but one thing that jumps out to me in the schema is that this hardcodes the steps:

  steps:
  - step1
  - step2
  - step3
  - step4
  step1:
    agent: agent1
  step2:
    agent: agent2
  step3:
    agent: agent1
  step4:
    agent: agent3

Could we define a step (singular) schema and then make steps (plural) a lists of steps ?

[george-lhj]

I commented in Aki's PR, but one thing that jumps out to me in the schema is that this hardcodes the steps:

steps:

• step1
• step2
• step3
• step4
  step1:
  agent: agent1
  step2:
  agent: agent2
  step3:
  agent: agent1
  step4:
  agent: agent3
  Could we define a step (singular) schema and then make steps (plural) a lists of steps ?

so are you suggesting something like:

steps:
  - name: step1
    agent: agent1
  - name: step2
    agent: agent2
  - name: step3
    agent: agent1
  - name: step4
    agent: agent3

[psschwei]

so are you suggesting something like:

correct

[maximilien]

Closing this #133 solves