rvf 0.1.0

# rvf - Rust ValueFlows Implementation

[![Rust](https://img.shields.io/badge/rust-1.70%2B-blue.svg)](https://www.rust-lang.org)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)

Rust implementation of the [ValueFlows](https://www.valueflo.ws/) vocabulary for distributed economic networks.

ValueFlows is a vocabulary for the distributed economic networks of the next economy, designed to coordinate the creation, distribution, and exchange of economic resources. It's based on the REA (Resources, Events, Agents) ontology.

## Features

- **Complete ValueFlows Implementation**: All core types including Agents, Resources, Events, Commitments, Intents, Processes, Transfers, Exchanges, Plans, Proposals, and Recipes
- **Production Ready**: Comprehensive error handling, extensive test coverage, and proper documentation
- **Serialization**: Full serde support for JSON and other formats
- **Storage Abstraction**: Pluggable storage backends with an in-memory implementation included
- **Type Safety**: Leverages Rust's type system to prevent invalid states
- **P2P Ready**: All types are serializable and designed for distributed systems

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
rvf = "0.1"
```

Or with specific features:

```toml
[dependencies]
rvf = { version = "0.1", features = ["full"] }
```

## Features Flags

- `serde` (default): Enable serialization/deserialization support
- `uuid` (default): Enable UUID generation for identifiers
- `async`: Enable async support for storage backends
- `full`: Enable all features

## Quick Start

```rust
use rvf::prelude::*;

// Create an agent (person, organization, or ecological agent)
let farmer = Agent::builder()
    .id("agent-001")
    .name("Local Farm")
    .agent_type(AgentType::Organization)
    .build()
    .unwrap();

// Create a resource specification (template/type of resource)
let tomato_spec = ResourceSpecification::builder()
    .id("spec-001")
    .name("Organic Tomatoes")
    .build()
    .unwrap();

// Create an economic resource
let tomatoes = EconomicResource::builder()
    .id("resource-001")
    .name("Farm Tomatoes Batch #1")
    .conforms_to(tomato_spec.id.clone())
    .primary_accountable(farmer.id.clone())
    .accounting_quantity(Measure::new(100, Unit::Kilogram))
    .build()
    .unwrap();
```

## Core Concepts

### Three Layers

ValueFlows operates in three layers:

1. **Knowledge Layer (Recipes)**: Templates and patterns for economic activity
2. **Plan Layer (Intents & Commitments)**: Offers, requests, and promises
3. **Observation Layer (Events)**: Records of what actually happened

### Key Types

#### Agents
Economic actors - people, organizations, or ecological agents.

```rust
let person = Agent::builder()
    .id("person-001")
    .name("Alice")
    .agent_type(AgentType::Person)
    .build()
    .unwrap();
```

#### Resources
Economic resources that can be created, transferred, or consumed.

```rust
let resource = EconomicResource::builder()
    .id("resource-001")
    .name("Wheat")
    .accounting_quantity(Measure::new(1000, Unit::Kilogram))
    .build()
    .unwrap();
```

#### Actions
Define what a flow does. Available actions:

- **Production**: `Produce`, `Consume`, `Use`, `Cite`
- **Work**: `Work`
- **Transportation**: `Pickup`, `Dropoff`
- **Modification**: `Accept`, `Modify`, `Combine`, `Separate`
- **Transfer**: `Transfer`, `TransferAllRights`, `TransferCustody`, `Move`
- **Digital**: `Copy`
- **Adjustment**: `Raise`, `Lower`
- **Service**: `DeliverService`

#### Events
Immutable records of economic activity.

```rust
let event = EconomicEvent::builder()
    .id("event-001")
    .action(ActionType::Produce)
    .provider("farmer-001")
    .receiver("farmer-001")
    .resource_inventoried_as("wheat-001")
    .resource_quantity(Measure::new(100, Unit::Kilogram))
    .build()
    .unwrap();
```

#### Commitments
Promises for future events.

```rust
let commitment = Commitment::builder()
    .id("commitment-001")
    .action(ActionType::Transfer)
    .provider("seller-001")
    .receiver("buyer-001")
    .resource_quantity(Measure::new(50, Unit::Each))
    .build()
    .unwrap();
```

#### Intents
Offers and requests that may lead to commitments.

```rust
// An offer (I want to give)
let offer = Intent::offer()
    .id("offer-001")
    .provider("seller-001")
    .action(ActionType::Transfer)
    .resource_quantity(Measure::new(10, Unit::Each))
    .build()
    .unwrap();

// A request (I want to receive)
let request = Intent::request()
    .id("request-001")
    .receiver("buyer-001")
    .action(ActionType::Transfer)
    .resource_quantity(Measure::new(10, Unit::Each))
    .build()
    .unwrap();

// Check if intents match
if offer.matches(&request) {
    println!("These intents are compatible!");
}
```

#### Processes
Transformations that take inputs and produce outputs.

```rust
let process = Process::builder()
    .id("process-001")
    .name("Bread Baking")
    .build()
    .unwrap();
```

#### Transfers
Movement of resources between agents.

```rust
let transfer = Transfer::builder()
    .id("transfer-001")
    .name("Wheat Sale")
    .transfer_type(TransferType::Both) // Rights + Custody
    .provider("seller-001")
    .receiver("buyer-001")
    .build()
    .unwrap();
```

#### Exchanges
Reciprocal transfers between parties.

```rust
let exchange = Exchange::builder()
    .id("exchange-001")
    .name("Wheat for Money")
    .build()
    .unwrap();
```

### Storage

The library provides a storage abstraction for persistence:

```rust
use rvf::storage::{Repository, InMemoryStorage, Storage};

// Create an in-memory repository
let repo = Repository::<Agent>::in_memory();

// Store an agent
repo.put("agent-001", agent.clone()).unwrap();

// Retrieve an agent
let retrieved = repo.get("agent-001").unwrap();

// Or use get_required which returns an error if not found
let agent = repo.get_required("agent-001").unwrap();
```

## Production Workflow Example

```rust
use rvf::prelude::*;

// 1. Define the participants
let farm = Agent::builder()
    .id("farm-001")
    .name("Happy Valley Farm")
    .agent_type(AgentType::Organization)
    .build()
    .unwrap();

let bakery = Agent::builder()
    .id("bakery-001")
    .name("Village Bakery")
    .agent_type(AgentType::Organization)
    .build()
    .unwrap();

// 2. Farm creates a wheat production process
let mut harvest = Process::builder()
    .id("process-001")
    .name("Wheat Harvest 2024")
    .build()
    .unwrap();

harvest.start();

// 3. Record the production event
let production = EconomicEvent::builder()
    .id("event-001")
    .action(ActionType::Produce)
    .provider(&farm.id)
    .receiver(&farm.id)
    .output_of(&harvest.id)
    .resource_quantity(Measure::new(1000, Unit::Kilogram))
    .build()
    .unwrap();

harvest.complete();

// 4. Farm publishes an offer
let offer = Intent::offer()
    .id("intent-001")
    .provider(&farm.id)
    .action(ActionType::Transfer)
    .resource_quantity(Measure::new(100, Unit::Kilogram))
    .build()
    .unwrap();

// 5. Bakery makes a matching request
let request = Intent::request()
    .id("intent-002")
    .receiver(&bakery.id)
    .action(ActionType::Transfer)
    .resource_quantity(Measure::new(100, Unit::Kilogram))
    .build()
    .unwrap();

// 6. Create a commitment when they agree
let mut commitment = Commitment::builder()
    .id("commitment-001")
    .action(ActionType::Transfer)
    .provider(&farm.id)
    .receiver(&bakery.id)
    .resource_quantity(Measure::new(100, Unit::Kilogram))
    .build()
    .unwrap();

// 7. Record the actual transfer
let transfer_event = EconomicEvent::builder()
    .id("event-002")
    .action(ActionType::Transfer)
    .provider(&farm.id)
    .receiver(&bakery.id)
    .resource_quantity(Measure::new(100, Unit::Kilogram))
    .fulfills(&commitment.id)
    .build()
    .unwrap();

// 8. Mark commitment as fulfilled
commitment.fulfill(Measure::new(100, Unit::Kilogram));
assert!(commitment.is_finished());
```

## Architecture Notes

### P2P Integration

All types implement `Clone`, `Debug`, and optionally `Serialize`/`Deserialize`, making them suitable for:

- Content-addressable storage (CAS)
- Distributed hash tables (DHT)
- Blockchain/DLT systems
- Event sourcing architectures

### Extensibility

The library is designed to be extended:

- Implement custom `Storage` backends for your persistence layer
- Add additional metadata through the `note` and `in_scope_of` fields
- Use the `Identifiable` trait for automatic ID extraction

## Examples

Run the included examples to see ValueFlows in action:

```bash
# Farm-to-bakery economic exchange
cargo run --example farm_to_bakery

# AI agent collaboration for research report production
cargo run --example ai_agent_collaboration
```

See [examples/README.md](examples/README.md) for detailed documentation, flow diagrams, and comparisons.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

## References

- [ValueFlows Specification](https://www.valueflo.ws/)
- [REA Ontology](http://rfrench.wikidot.com/rea-ontology)
- [ValueFlows GitHub](https://github.com/valueflows)