sevensense-core

Shared domain primitives for the 7sense bioacoustic intelligence platform.

sevensense-core provides the foundational types, traits, and utilities used across all 7sense crates. It defines the core vocabulary of the domain—species identifiers, temporal boundaries, audio metadata, and error types—ensuring consistency throughout the platform.

Features

• Species Taxonomy: Type-safe species identifiers with scientific/common name support
• Temporal Primitives: Time ranges, segments, and duration utilities for audio analysis
• Domain Events: Event-sourced primitives for audit trails and streaming
• Error Handling: Unified error types with rich context and error chains
• Configuration: Shared configuration primitives and validation

Use Cases

Installation

Add to your Cargo.toml:

[dependencies]
sevensense-core = "0.1"

Quick Start

use sevensense_core::{SpeciesId, TimeRange, AudioMetadata};

// Create a species identifier
let species = SpeciesId::from_scientific("Turdus merula");
println!("Species: {}", species.scientific_name());

// Define a time range for analysis
let range = TimeRange::new(
    chrono::Utc::now() - chrono::Duration::hours(1),
    chrono::Utc::now()
);
println!("Duration: {:?}", range.duration());

Creating Species Identifiers

use sevensense_core::{SpeciesId, TaxonomicRank};

// From scientific name
let blackbird = SpeciesId::from_scientific("Turdus merula");

// With common name
let blackbird = SpeciesId::new("Turdus merula", Some("Eurasian Blackbird"));

// Check taxonomic information
assert_eq!(blackbird.genus(), "Turdus");
assert_eq!(blackbird.species_epithet(), "merula");

Species Collections

use sevensense_core::{SpeciesRegistry, SpeciesId};

let mut registry = SpeciesRegistry::new();
registry.register(SpeciesId::from_scientific("Turdus merula"));
registry.register(SpeciesId::from_scientific("Turdus philomelos"));

// Search by partial name
let thrushes = registry.search("Turdus");
println!("Found {} thrush species", thrushes.len());

Basic Time Ranges

use sevensense_core::TimeRange;
use chrono::{Utc, Duration};

// Create a range for the last hour
let now = Utc::now();
let range = TimeRange::new(now - Duration::hours(1), now);

// Check duration
println!("Range spans: {:?}", range.duration());

// Check if a timestamp is within range
let test_time = now - Duration::minutes(30);
assert!(range.contains(test_time));

Splitting Time Ranges

use sevensense_core::TimeRange;
use chrono::Duration;

let range = TimeRange::last_n_hours(24);

// Split into 1-hour windows
let windows = range.split_by_duration(Duration::hours(1));
println!("Created {} 1-hour windows", windows.len());

// Split into equal parts
let parts = range.split_into_n_parts(4);
assert_eq!(parts.len(), 4);

Using Core Errors

use sevensense_core::{CoreError, CoreResult, ErrorContext};

fn process_audio(path: &str) -> CoreResult<()> {
    // Operations that might fail
    let file = std::fs::File::open(path)
        .map_err(|e| CoreError::io(e).with_context("opening audio file"))?;

    Ok(())
}

fn main() {
    match process_audio("missing.wav") {
        Ok(_) => println!("Success!"),
        Err(e) => {
            eprintln!("Error: {}", e);
            if let Some(ctx) = e.context() {
                eprintln!("Context: {}", ctx);
            }
        }
    }
}

Error Chains

use sevensense_core::{CoreError, CoreResult};

fn outer_function() -> CoreResult<()> {
    inner_function()
        .map_err(|e| e.with_context("in outer_function"))?;
    Ok(())
}

fn inner_function() -> CoreResult<()> {
    Err(CoreError::validation("Invalid input"))
}

API Overview

Core Types

Traits

License

MIT License - see LICENSE for details.