commons/README.md

Commons

Commons is the shared type library for Shoal - common types used across all components.

What it Does

Commons provides consistent, reusable types throughout the Shoal system:

• Shared data structures - Types used by Pod, Reef, Reservoir, Dock, Lookout
• Optional TTP serialization - Types can be serialized using TTP (Transport Type Protocol)
• Cross-crate consistency - Ensures all components use the same type definitions

How to Use

Dependencies

Add to your Cargo.toml:

shoal-types = { git = "https://git.methanium.net/shoal/commons.git" }

Usage

Import common types:

use common::{Task, KrillConfig, ProjectMetadata, ...};

Purpose

Instead of each component defining its own types, Commons centralizes:

• Communication message types (including training progress, control signals)
• Task definitions (JobType::Task, JobType::Training, JobType::DataPreparation)
• Training job payloads (TrainingJob, InferenceJob, TrainingMetrics, TrainingControl)
• Configuration structures
• Storage schemas

This ensures type safety and consistency across the entire Shoal ecosystem.