Crate stigmergy

Expand description

§Stigmergy: Emergent Coordination through Shared Data Structures

Stigmergy is a biological concept describing how organisms coordinate their activities through modifications to their shared environment. Ants building trails, termites constructing mounds, and birds flocking all demonstrate stigmergic behavior - simple local actions that produce complex global coordination without central control.

This crate implements a stigmergic system for software, providing:

Entity-Component Architecture: Entities are unique identifiers that can have multiple components attached, following ECS (Entity Component System) patterns
Schema Validation: Components are validated against JSON schemas to ensure data integrity and consistency
PostgreSQL Storage: All entities and components are persisted in PostgreSQL
HTTP API: RESTful endpoints for managing entities and components
Configuration Management: System configuration through frontmatter-delimited files

§Core Concepts

§Entities

Entities are 32-byte identifiers encoded as URL-safe base64 strings with an “entity:” prefix. They serve as unique handles in the system and can be randomly generated or explicitly specified.

§Components

Components are typed data structures that can be attached to entities. Each component has a Rust-style type path identifier (e.g., “Position”, “std::collections::HashMap”) and JSON data that must conform to a predefined schema.

§Validation

All component data is validated against JSON schemas that support:

Primitive types (null, boolean, integer, number, string)
Complex types (arrays, objects)
Enumerations and union types via oneOf
Nested structures with full recursion

§Persistence

All entities, components, and their relationships are stored in PostgreSQL with automatic timestamp tracking for creation and modification events.

§Architecture

The system follows a layered architecture:

┌─────────────────────────────────────────┐
│ HTTP API Layer (Axum routes)            │
├─────────────────────────────────────────┤
│ Business Logic (Component operations)   │
├─────────────────────────────────────────┤
│ PostgreSQL Database (Persistent storage)│
└─────────────────────────────────────────┘

§Usage Examples

§Creating and Managing Entities

// Create a new entity with a specific ID
let entity = Entity::new([1u8; 32]);
let entity_str = entity.to_string(); // "entity:AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE"

// Parse an entity from its string representation
let parsed: Entity = entity_str.parse().unwrap();
assert_eq!(entity, parsed);

// Generate a random entity
let random_entity = Entity::random_url_safe().unwrap();

§Component Schema Definition

Component schemas can be created manually or automatically generated using the derive macro:

// Manual schema definition
let component = Component::new("Position").unwrap();

let schema = json!({
    "type": "object",
    "properties": {
        "x": { "type": "number" },
        "y": { "type": "number" },
        "z": { "type": "number" }
    },
    "required": ["x", "y"]
});

let definition = ComponentDefinition::new(component, schema);

// Validate component data
let valid_data = json!({"x": 1.0, "y": 2.0, "z": 3.0});
assert!(definition.validate_component_data(&valid_data).is_ok());

§Automatic Schema Generation

Use the JsonSchemaDerive macro to automatically generate schemas for structs and enums:

// Define types with automatic schema generation
#[derive(stigmergy_derive::JsonSchema)]
struct Position {
    x: f64,
    y: f64,
    z: Option<f64>,
}

#[derive(stigmergy_derive::JsonSchema)]
enum Status {
    Active,
    Inactive,
    Pending,
}

#[derive(stigmergy_derive::JsonSchema)]
enum Shape {
    Circle { radius: f64 },
    Rectangle { width: f64, height: f64 },
}

// Generate schemas automatically
let position_schema = Position::json_schema();
let status_schema = Status::json_schema();
let shape_schema = Shape::json_schema();

// Unit enums become string enums
assert_eq!(status_schema["type"], "string");
assert!(status_schema["enum"].as_array().unwrap().len() == 3);

// Complex enums use oneOf patterns
assert!(shape_schema["oneOf"].is_array());

Modules§

cli_utils: Command-line interface utilities for program termination and output formatting.
commands: Command-line interface command handlers.
component_utils: Component-specific utilities for validation and creation.
http_utils: HTTP client utilities for interacting with stigmergy services.
sql: PostgreSQL database operations for stigmergy.

Structs§

Bid: A complete bid expression with condition and value
BidParser: Main parser for bid expressions
Component: A component type identifier that follows Rust naming conventions.
ComponentAccess: Represents a component and its access mode for a system.
ComponentDefinition: A component definition that associates a component type with its JSON schema.
ComponentListItem: A component instance item used in list responses.
CreateComponentRequest: Request structure for creating a new component instance.
CreateComponentResponse: Response structure for successful component creation.
CreateEntityRequest: Request structure for creating a new entity.
CreateEntityResponse: Response structure for entity creation.
CreateInvariantRequest: Request structure for creating a new invariant.
CreateInvariantResponse: Response structure for invariant creation.
CreateSystemFromMarkdownRequest: Request structure for creating a system from markdown content.
CreateSystemResponse: Response structure for system creation.
Entity: A 32-byte entity identifier with URL-safe base64 string representation.
GetInvariantResponse: Response structure for getting an invariant.
InvariantID: A 32-byte invariant identifier with URL-safe base64 string representation.
JsonSchemaBuilder: A JSON schema representation that can be used for validation and documentation.
Position: Position information for error reporting
System: A system represents a Claude Code agent configuration with its associated metadata. Systems are identified by their name.
SystemConfig: A parsed system configuration containing metadata and content.
SystemListItem: List item for systems (simplified view).
SystemName: A strongly-typed system name identifier.
SystemNameParseError: Error returned when parsing an invalid system name.
SystemParser: Parser for system configuration files with frontmatter and markdown content.
UpdateInvariantRequest: Request structure for updating an invariant.

Enums§

AccessMode: Represents the access mode for a component in a system.
BidParseError: Errors that can occur during bid parsing
BinaryOperator: Binary operators with precedence information
DataStoreError: Errors that can occur during data store operations.
EntityParseError: Errors that can occur when parsing an Entity from a string.
EvaluationError: Errors that can occur during bid evaluation
Expression: A parsed expression that can be evaluated
InvariantIDParseError: Errors that can occur when parsing an InvariantID from a string.
ParseError: Errors that can occur when parsing system configuration files.
UnaryOperator: Unary operators
ValidationError: Errors that can occur during JSON schema validation.

Traits§

EntityResolver: A trait for resolving keys into JSON entities. This allows the evaluation engine to work with normalized or relational data structures.
JsonSchema: Trait for types that can generate their own JSON Schema

Functions§

create_component_definition_router: Creates the HTTP router for component definition endpoints.
create_component_instance_router: Creates an Axum router with component instance management endpoints.
create_entity_router: Creates an Axum router with entity management endpoints.
create_invariant_router: Creates an Axum router with invariant management endpoints.
create_system_router: Creates an Axum router with system management endpoints.
validate_value: Validates a JSON value against a JSON schema.

Crate stigmergy

Crate stigmergy Copy item path

§Stigmergy: Emergent Coordination through Shared Data Structures

§Core Concepts

§Entities

§Components

§Validation

§Persistence

§Architecture

§Usage Examples

§Creating and Managing Entities

§Component Schema Definition

§Automatic Schema Generation

Modules§

Structs§

Enums§

Traits§

Functions§

Crate stigmergy