feagi-serialization 0.0.1-beta.4

Adds serialization and deserialization to select Feagi Data Structures.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

# feagi-serialization

**Efficient serialization and deserialization for FEAGI data structures**

[![Crates.io](https://img.shields.io/crates/v/feagi-serialization.svg)](https://crates.io/crates/feagi-serialization)
[![Documentation](https://docs.rs/feagi-serialization/badge.svg)](https://docs.rs/feagi-serialization)
[![License](https://img.shields.io/crates/l/feagi-serialization.svg)](LICENSE)

## Overview

`feagi-serialization` provides high-performance serialization and deserialization for FEAGI data structures. This crate implements the FEAGI Byte Container (FBC) format for efficient binary encoding of neural data.

## Features

- **FEAGI Byte Container (FBC)**: Efficient binary container format
- **Multiple Structure Types**: Support for JSON, raw images, and XYZP neuron data
- **Cortical Mapped Data**: Serialization for cortical-area-mapped neuron voxels
- **Zero-Copy Operations**: Where possible, for maximum performance
- **Type-Safe Deserialization**: Strongly typed structure identification

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
feagi-serialization = "0.0.1-beta.1"
feagi-structures = "0.0.1-beta.1"
```

## Usage

### FEAGI Byte Container

```rust
use feagi_serialization::{FeagiByteContainer, FeagiByteStructureType};

// Create a container with JSON data
let json_data = br#"{"cortical_id": "ipu000", "data": [1,2,3]}"#;
let container = FeagiByteContainer::new(
    FeagiByteStructureType::Json,
    json_data.to_vec()
);

// Serialize to bytes
let bytes = container.to_bytes();

// Deserialize from bytes
let decoded = FeagiByteContainer::from_bytes(&bytes)?;
```

### Cortical Mapped XYZP Data

```rust
use feagi_serialization::implementations::cortical_mapped_xyzp_neuron_data::CorticalMappedXYZPNeuronVoxels;
use feagi_structures::genomic::cortical_area::CorticalID;

// Create neuron data mapped to cortical areas
let cortical_id = CorticalID::from_base_64("aXB1MDAw")?;
let mut data = CorticalMappedXYZPNeuronVoxels::new();

// Add voxels for a cortical area
data.insert(cortical_id, vec![(10, 20, 5, 128)]);

// Serialize efficiently
let bytes = data.serialize_to_bytes();
```

## Supported Structure Types

- **JSON** (Type 0x01): Standard JSON encoding
- **Single Raw Image** (Type 0x08): Raw image data
- **XYZP Neuron Data** (Type 0x0B): Neuron voxel potential data

See [documentation](docs/byte_structure_container.md) for the complete format specification.

## Performance

The FBC format is designed for high-throughput neural data transmission:

- Minimal overhead (8-byte header)
- Type identification for fast routing
- Optional compression support
- Efficient for large batches of neuron data

## Documentation

For detailed API documentation, visit [docs.rs/feagi-serialization](https://docs.rs/feagi-serialization).

For format specifications, see the [docs/](docs/) directory.

## Part of FEAGI Ecosystem

This crate is part of the FEAGI project:

- **Main Project**: [feagi](https://crates.io/crates/feagi)
- **Data Structures**: [feagi-structures](https://crates.io/crates/feagi-structures)
- **Sensorimotor**: [feagi-sensorimotor](https://crates.io/crates/feagi-sensorimotor)

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](../../LICENSE) for details.

## Contributing

Contributions are welcome! Please see the [main repository](https://github.com/feagi/feagi-core) for contribution guidelines.

## Links

- **Homepage**: https://feagi.org
- **Repository**: https://github.com/feagi/feagi-core
- **Documentation**: https://docs.rs/feagi-serialization
- **Issue Tracker**: https://github.com/feagi/feagi-core/issues