Cobuy as Value Flows

[fosterlynn]

@ahdinosaur is this a good way to give feedback? (Ref. https://github.com/valueflows/valueflows/issues/127)

I just started looking and have one initial comment, will have more when I get deeper.

"Supplier" is probably a relationship type, not an agent type. Like maybe one of your members grows a lot of garlic and offers it to the coop or buying club.

[ahdinosaur]

this is great, thanks @fosterlynn

[fosterlynn]

I did another round of looking.

I'm not sure you want to create a new Agent (purchase group) for each order. The people would just naturally fall into relationships around the order when they express their requests for that order. And I believe the Coop is the agent that makes the order, if I am reading correctly. That is, the purchase group doesn't have that much agency. I do read that a person can be a facilitator for a purchase group. But perhaps that could be a work assignment with type of work = facilitation (a resource type) rather than a role of a group?

Note: Please ignore the above if it doesn't feel right to you. To me it is a gut feeling that Agents (Groups) should be a bit more permanent, and people can associate around a particular batch of work in other ways (including say making an order).

This could be one or a series of Processes with different work inputs, and also of course Transfers/Exchanges, maybe first between the supplier and the coop, then between the coop and each orderer?

I don't know if we will end up with Order in the VF vocab or not. A customer/supplier order could be an Exchange or a set of Transfers with commitments for each item ordered and to pay the supplier. A "work order" could be a set of processes that together create one or more things, like say an order. Or maybe those could be combined, we haven't explored all of that territory. I think we will need something like work order, to group processes into a logical grouping with an output, which is what you are using the purchase group for. This might be like the little-p process.

I hope that wasn't totally convoluted! Questions welcome, or @ahdinosaur if you want to work through this together sometime in a call, that would be pretty interesting.

[ahdinosaur]

hey @fosterlynn @bhaugen, just a heads up, i'm starting development of Cobuy using catstack.

the first release will be the second and third screens on the first image: basically enough to demo how many people can input their preferences on a bulk order and see the result.

my plan is to get something working, then have a discussion on how our data model converges with the latest Value Flows discussions (except using an append-only log of data messages like Scuttlebutt instead of RDF-style linked open data).

sorry for the delay, but it's happening!

[ahdinosaur]

some notes on initial data model:

- supplier
  - name: string
- order
  - [resource]
- resource type
  - ([resource types])
  - name: string
- supply type
  - supplier
  - resource type
  - batch size: quantity
  - [supply cost]
- supply cost
  - min batches: number
  - price per batch: quantity
- quantity
  - value: number
  - unit: enum

where (...) means optional and [...] means many.

/cc @mischa-saunders @bill-burgess

[fosterlynn]

@ahdinosaur great!! Looking forward to your demo...

my plan is to get something working, then have a discussion on how our data model converges with the latest Value Flows discussions (except using an append-only log of data messages like Scuttlebutt instead of RDF-style linked open data).

Your initial data model is a bit confusing to me, but that's ok. :) I'd love to map it to VF with you whenever you want! Or just walk through it together if that would be helpful to you.

Will be very interesting to see how this plays out in Scuttlebutt! I think it is important to have VF support more than RDF-style data.

[ahdinosaur]

another round of data modelling! :tada:

---

data model included as part of dogstack-agents

- agents
  - id
- agentCredentials
  - type
- agentProfiles
  - id
  - agentId
  - name
  - image
  - description
- agentRelationships
  - sourceAgentId
  - relationshipType
  - targetAgentId
  - scope
- agentRelationshipTypes
  - id
  - name
  - description

---

rest of data model overview:

(inspired by https://github.com/valueflows/valueflows/pull/115 and https://github.com/enspiral-root-systems/nanox/issues/11)

- resourceType
  - id
  - name
  - image
  - description
- resource
  - id
  - resourceType
  - location
- location
  - id
  - name
  - image
  - description
- template
  - action: json
  - paramsSchema: json
- action
  - source
  - type: enum(give)
  - target
  - quantity
    - unit
    - value
    - if quantity is for consumer intent, it has:
      - desiredValue
      - minimumValue
      - maximumValue
    - if quantity is for supplier commitment, it has:
      - minimumValue
  - resource
- signal
  - agentId
  - type: enum(intent, plan, flow)
  - template
  - params: json
- quantity
  - id
  - value
  - unit: enum(kg, resource)
- unit
  - id
  - name
  - abbreviation
  - dimension
  - description

---

Cobuy process design using data models:

(1) supplier inventory

template

name: sell
action:
  - source: ${supplier}
    type: give,
    target: ${consumer}
    quantity:
      value: ${quantity}
      unit: each
      minimum: ${minimum}
    resource: ${product}
  - source: ${consumer}
    type: give
    target: ${supplier}
    quantity:
      value: ${price} * ${quantity}
      unit: each
    resource: ${currency}
schema:
  type: 'object'
  properties:
    supplier:
      type: 'string'
      format: 'id'
    consumer:
      type: 'string'
      format: 'id'
    price:
      type: 'string'
      format: 'decimal'
    quantity:
      type: 'string'
      format: 'decimal'
    minimum:
      type: 'string'
      format: 'decimal'

the data IS the user interface!

signal

agent: Supplier
type: intent
template: sell
params:
  supplier: me
  price: 1
  minimum: 10

(2) individual consumer pledge

template

name: pre-buy
action: 
  - source: ${supplier}
    type: give,
    target: ${consumer}
    quantity:
      desired: ${desired}
      minimum: ${minimum}
      maximum: ${maximum}
      unit: each
    resource: ${product}
  - source: ${consumer}
    type: give
    target: ${supplier}
    quantity:
      value: ${price} * ${quantity}
      unit: each
    resource: ${currency}
schema:
  type: 'object'
  properties:
    supplier:
      type: 'string'
      format: 'id'
    consumer:
      type: 'string'
      format: 'id'
    resource:
      type: 'string'
      format: 'id'
    price:
      type: 'string'
      format: 'decimal'
    desired:
      type: 'string'
      format: 'decimal'
    minimum:
      type: 'string'
      format: 'decimal'
    maximum:
      type: 'string'
      format: 'decimal'

signal

agent: Consumer
type: intent
template: pre-buy
params:
  consumer: me
  supplier: them
  resource: avocado
  price: 1
  minimum: 1
  desired: 2
  maximum: 3

(3) consumer group order

name: buy
action: 
  - source: ${supplier}
    type: give
    target: ${consumer}
    quantity:
      value: ${quantity}
      unit: each
    resource: ${product}
  - source: ${consumer}
    type: give
    target: ${supplier}
    quantity:
      value: ${cost}
      unit: each
    resource: ${currency}
schema:
  type: 'object'
  properties:
    supplier:
      type: 'string'
      format: 'id'
    consumer:
      type: 'string'
      format: 'id'
    resource:
      type: 'string'
      format: 'id'
    quantity:
      type: 'string'
      format: 'decimal'
    cost:
      type: 'string'
      format: 'decimal'
    currency:
      type: 'string'
      format: 'id'

signal

agent: ConsumerGroup
type: plan
intent: consumer intents
params:
  consumer: us
  supplier: supplier
  resource: avocado
  quantity: 10
  cost: $100
  currency: NZD

(4) consumer group order received

signal

agent: ConsumerGroup
type: flow
input: consumer group plan
params:
  consumer: us
  supplier: supplier
  resource: avocado
  quantity: 8
  cost: $100
  currency: NZD

[ahdinosaur]

I'm not sure you want to create a new Agent (purchase group) for each order. The people would just naturally fall into relationships around the order when they express their requests for that order. And I believe the Coop is the agent that makes the order, if I am reading correctly. That is, the purchase group doesn't have that much agency. I do read that a person can be a facilitator for a purchase group. But perhaps that could be a work assignment with type of work = facilitation (a resource type) rather than a role of a group?

Note: Please ignore the above if it doesn't feel right to you. To me it is a gut feeling that Agents (Groups) should be a bit more permanent, and people can associate around a particular batch of work in other ways (including say making an order).

This could be one or a series of Processes with different work inputs, and also of course Transfers/Exchanges, maybe first between the supplier and the coop, then between the coop and each orderer?

A "work order" could be a set of processes that together create one or more things, like say an order. I think we will need something like work order, to group processes into a logical grouping with an output, which is what you are using the purchase group for. This might be like the little-p process.

re-reading your comments with fresh context @fosterlynn, i like your idea to approach with "work streams", interested in how to apply that as a data model. do you have data model examples of this in NRP or Value Flows?

[ahdinosaur]

found some relevant discussions in Value Flows issues:

• https://github.com/valueflows/valueflows/issues/174
• https://github.com/valueflows/valueflows/issues/148
• https://github.com/valueflows/valueflows/issues/109
• https://github.com/valueflows/valueflows/issues/106

from what i understand, we want to model the entire order process as a series of steps that connect outputs from the previous steps to the inputs of the next step, with each step having input work actions by the agent acting as order facilitator using their hours as a resource.

so at a high level something like:

- supplier inventory entry process:
  - inputs:
    - facilitator work hours
  - outputs:
    - supplier resource types
    - supplier plans to sell resource types
- for each consumer, pre-buy intent process:
  - inputs:
    - supplier resource types
    - supplier plans to sell resource types
    - facilitator work hours
    - consumer work hours
  - outputs:
    - consumer pre-buy intent
- group buy tweaking process:
  - inputs:
    - consumer intents by each consumer
    - facilitator work hours
  - outputs:
    - group buy plan
- group order send:
  - inputs:
    - group buy plan
    - facilitator work hours
  - outputs:
    - group order

:heart_eyes_cat:

directly modelling these "work streams" could be how we handle both notifications and an audit log. the best part about this approach is that it matches perfectly with the next stage of the app workflow: receiving the order, delegating packing tasks, doing packing, hosting pick-up, doing pick-up, etc. should also work well with keeping track of any one-off tasks like sending emails or editing details or bringing containers. /cc @agentlewis

[danalexilewis]

nicely documented @ahdinosaur It's funny how much sense the nanox stuff makes to me now. I think I needed the paper talk through back when you wrote it :)

[fosterlynn]

Wow @ahdinosaur looks like you all been thinking! I'll take some time to digest the detail tomorrow, and see if we are missing anything in ValueFlows from your on-the-ground work. And if you want comments, I can do that too, especially since there have been a number of evolutions over in VF. :blush:

[ahdinosaur]

And if you want comments

yes please!

[fosterlynn]

@ahdinosaur I'm going to plop questions here as they come up:

What is an action vs a signal?

[fosterlynn]

re-reading your comments with fresh context @fosterlynn, i like your idea to approach with "work streams", interested in how to apply that as a data model. do you have data model examples of this in NRP or Value Flows?

In VF we haven't nailed down recipes, although the plan and observation parts are pretty nailed down - except intents not really. Maybe it would help to look at Bob's Vocabulator, I don't know. http://valueflows.pythonanywhere.com/ Or this is more or less a data model, partially complete: https://valueflows.gitbooks.io/valueflows/content/specification/diagrams/uml.html. And the rest of that gitbook is pretty much the latest.

NRP has recipes of different kinds, here is a simplifed core data model, with recipes on the top. But the pattern at each level is basically the same, too.

from what i understand, we want to model the entire order process as a series of steps that connect outputs from the previous steps to the inputs of the next step, with each step having input work actions by the agent acting as order facilitator using their hours as a resource.

Your sequence looks great to me! Can you do it so it is simple for people?

OK, I'm still trying to wrap my head over the whole thing, but am done for today.

Question: do you want to use VF vocab for all of this? Or does it matter? Is it all internally hidden, or is it one of your mad science distributed ssb or similar kind of thing? :)

[ahdinosaur]

What is an action vs a signal?

it's a continuation of my simplified Value Flows idea, but with a slightly better understanding of the concepts.

Question: do you want to use VF vocab for all of this? Or does it matter?

depends on what you mean by VF vocab. :wink: if you mean the conceptual vocabulary, then yes that's what i'm hoping to talk about here! if you mean the current JSON-LD implementation of the conceptual vocabulary, then no, since i think we can do better and want to try alternative approaches.

Is it all internally hidden, or is it one of your mad science distributed ssb or similar kind of thing? :)

in the end we're probably going to focus on working software, using plain ole' SQL databases before too much mad science. :smile: but i would like Cobuy to be a "Value Flows-native" app (using the concepts in the core data structures rather than just for inter-operablity), even if there's unexplored territory about specific implementation details.

[bhaugen]

if you mean the current JSON-LD implementation of the conceptual vocabulary, then no, since i think we can do better and want to try alternative approaches.

We want to support many formats. In the Vocabulator we currently output turtle, json-ld, json, yaml, n3, n-triples, and rdf+xml. Want to add CSV. Got any other ideas?

[ahdinosaur]

Got any other ideas?

i'm mainly interested in the developer experience of building a "VF-native" app. i think this is one of those things where i don't actually know how the current approach can be improved, since i'm still trying to understand how Value Flows works in practice, but i'd rather explore following my intuition, which is designing data structures i understand enough to explain to my co-workers while we build something.

[bhaugen]

If you got a use case I can implement in the Vocabulator, and an output format to try, I'll try it as soon as the required concepts are agreed upon by the VF gang. Of which you are one. So meow up. :smile_cat:

[fosterlynn]

i'm mainly interested in the developer experience of building a "VF-native" app. i think this is one of those things where i don't actually know how the current approach can be improved, since i'm still trying to understand how Value Flows works in practice, but i'd rather explore following my intuition, which is designing data structures i understand enough to explain to my co-workers while we build something.

@ahdinosaur thanks, and awesome too! :heart: And yes, we all gotta do some experimenting on it, and I definitely take it as a 2-way street. I have thought of VF as needed between pieces of software that want to talk to each other (of whatever size, depending on how mad your science is), and whatever people want and need to do inside is encapsulated for them. At the same time, I'm still contemplating what it means to be a "VF-native" app, and I think I need to broaden my view based on your comments.

conceptual vocabulary

:+1:

P.S. Already reaped something for VF: minimum and maximum on the intent.

P.P.S. Thanks for directing me back to your simplified VF ideas doc, will re-read, and possibly harvest.

OK, enough general chat from me, will go back to the data detail questions today. :smile:

[bhaugen]

Possibly unlike Lynn, I am very interested in VF native apps.

[ahdinosaur]

what it means to be a "VF-native" app

my current thinking is that a "VF-native" app means you embrace Value Flows as the primary design pattern in your app architecture, rather than building your app and translating it to Value Flows later. in practice this might mean you use Value Flows concepts in how you write your app data models, hopefully even as a re-usable module (library) you can import into your app's code, not just Value Flows as an "import" and "export" data format.

or said another way, i remember @simontegg sharing an idea about there being two ways of designing data models, one where your data models reflect your user' activity process (for example, Cobudget with data models like group, user, bucket, allocation, contribution), another where your data systems reflect a simpler model that can be used to model many different activities. i think the former leads to quicker immediate results (and seems aligned with "lean"), but doing VF-native means you incur the cost of necessary complexity upfront in a proactive way rather than reactively later ("simplicity-oriented design").

so basically i want to make Value Flows a part of a JavaScript framework: dogstack, and already started with agents :dog:

[bhaugen]

my current thinking is that a "VF-native" app means you embrace Value Flows as the primary design pattern in your app architecture, rather than building your app and translating it to Value Flows later.

Yeah. that's what I mean, too. But it comes in two flavors: conventional apps, and flocks of tiny apps where each app might implement one and only one of the VF "primitives" and they meet on the internets and work together in various patterns.

One of the REA app gang has fallen in love with the Scuttleverse and wants to work with Cel to develop an SSB mutual credit system. It might be like a flock of apps.

or said another way, i remember @simontegg sharing an idea about there being two ways of designing data models, one where your data models reflect your user' activity process (for example, Cobudget with data models like group, user, bucket, allocation, contribution), another where your data systems reflect a simpler model that can be used to model many different activities. i think the former leads to quicker immediate results (and seems aligned with "lean"), but doing VF-native means you incur the cost of necessary complexity upfront in a proactive way rather than reactively later ("simplicity-oriented design").

That's an interesting perspective, and I am familiar. I think in practice we will end up with both, working together. For examples:

• I think if you are doing an economic app, somewhere in the guts you will be forced to implement some of the VF economic concepts and economic logic, most likely with different names and some variations.
• In NRP we got the whole band of VF concepts, and then Value Equations, which stole Buckets from Cobudget, and have a model of the breakdown of some income into payments for contributions.
• Conversations for Action are everywhere in economic exchanges. They are not the same as the VF Exchange concepts, but they use them. They are examples of what I call a human-level protocol, although I haven't had much luck getting people to understand that CfA is a protocol. But I'll bet you have some human-level protocols in Cobuy, too. Those will have their own model and logic but use the economic concepts. CfA, for example, fits fairly neatly into a state machine.
• When we worked with food networks, which are related but not the same as Cobuy, we ran into a bunch of interesting patterns around orders and deliveries that we should summarize some time. Some combinations of joins and splits and joins and splits.

so basically i want to make Value Flows a part of a JavaScript framework: dogstack, and already started with agents :dog:

Love it! Want to use it! Slight problem or opportunity, the REA app is developing something with the same goals, but they could not grasp your javascript architecture, so they are going with more vanilla React. Will be interesting to compare them as they evolve...and see if they can talk to each other.

[fosterlynn]

rest of data model overview

excerpt from above:

- action
  - source
  - type: enum(give)
  - target
  - quantity
    - unit
    - value
    - if quantity is for consumer intent, it has:
      - desiredValue
      - minimumValue
      - maximumValue
    - if quantity is for supplier commitment, it has:
      - minimumValue
  - resource
- signal
  - agentId
  - type: enum(intent, plan, flow)
  - template
  - params: json

In terms of VF, I think you may have bundled the vf:Process and vf:EconomicEvent into one thing? Or possibly the above is meant to address only the exchanges?

Speaking of exchanges, we have a new model (different than NRP), which can use any vf:action (event type) as part of an exchange. Like you can exchange work for something else, for example. We're still trying to make sure the processes and exchange play nicely together, so this is a good use case.

Another area of difference I see is that you have made the corresponding objects on the 3 layers the same schema, and just typed them. VF has them as different classes. Either would probably work.

And VF would think of the suppliers' offers for sale as intents, not plans yet (although we don't have the term "plan" anyway). When an order is made (and maybe confirmed?), it would be more like a plan. or a vf:Commitment. Also, when a work plan is made, if nobody has committed to a task, it is still an Intent.

Here is a beginning attempt to put it into the current VF vocab / structure, hope it is understandable, and at least food for thought/discussion. It is the "relational/object" version. :)

- Action [this is the NRP event type, "work", "consume", "use", "produce", etc.- but also "issue", "receive", "load", "unload"... and more will emerge.  We don't know yet if we have "transfer", or "give"/"take".]
  - name 
  - resourceEffect (increment, decrement, no effect)
- Intent [we haven't nailed Intent down, this is a guess]
  - action: Action [will imply whether it is an offer or a request we think]
  - provider (== source)
  - receiver (== target) [need provider or receiver]
  - if quantity is for consumer intent, it has:
    - requestedQuantity? (~= desiredValue)
    - minimumQuantity? (~= minimumValue)
    - maximumQuantity? (~= maximumValue)
   - if quantity is for supplier intent, it could have:
     - minimumQuantity? (~= minimumValue)
  - resourceType [this likely won't be the name in VF, but it is as good as any for now]
- Commitment (Intents have been matched and firmed up - like an order, or someone committing to a task)
  - action: Action
  - provider (== source)
  - receiver (== target)
  - committedQuantity (== quantity)
  - involves?: resourceType (could be an actual resource, but probably not in your case)
  - commits?: Intent (optional)
- EconomicEvent
  - action: Action
  - provider (== source)
  - receiver (== target)
  - affectedQuantity (== quantity)
  - affects: EconomicResource [could be not an inventoried resource, could include just resourceType]
  - start: a date
  - fulfills:  Commitment or Intent (optional) 
- Process
  - name ["supplier inventory entry process", "pre-buy intent process", etc.]
  - inputs? (collection of EconomicEvents, Commitments, Intents)
  - outputs? (collection of EconomicEvents, Commitments, Intents)
- ExchangeAgreement
  - probably some kind of name or type, like your "sell", "pre-buy"?
  - commitments? (collection of Commitments)

You also might want to add 'quantity' to the following, to make it easier to work with:

- resource
  - id
  - resourceType
  - location

And there would be notifications coming off of various events, which wouldn't show up in the data model unless you get into where there is conversation back and forth. We haven't done much yet with the conversations for action/agreement in VF for actual vocabulary and protocol.

I think this would be much more useful if it is laid out as an example, kind of like you did above. I'm noticing that the static schema didn't address the process vs exchange interconnection questions I have for myself. Depending on what this brings, I could try that.

But let me know if I am mis-understanding anything that I should understand!

[ahdinosaur]

/cc @mmckegg

[ahdinosaur]

/cc @gregorykan

[fosterlynn]

hey @ahdinosaur as soon as I have more time (maybe in a few days?), I'll do something more instance related and friendlier to look at...... :)