feagi_services/types/
dtos.rs

1// Copyright 2025 Neuraville Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4/*!
5Transport-agnostic Data Transfer Objects (DTOs).
6
7These types define the stable contract between adapters and services.
8They can be serialized to JSON, MessagePack, Protobuf, or any other format.
9
10Copyright 2025 Neuraville Inc.
11Licensed under the Apache License, Version 2.0
12*/
13
14use serde::{Deserialize, Serialize};
15use std::collections::HashMap;
16
17// ============================================================================
18// IO CODING DTOs
19// ============================================================================
20
21/// IO coding options for IPU/OPU cortical areas.
22#[derive(Debug, Clone, Serialize, Deserialize)]
23pub struct IOCodingOptions {
24    pub signage_options: Vec<String>,
25    pub behavior_options: Vec<String>,
26    pub coding_type_options: Vec<String>,
27}
28
29// ============================================================================
30// NEURON DTOs
31// ============================================================================
32
33/// Information about a neuron
34#[derive(Debug, Clone, Serialize, Deserialize)]
35pub struct NeuronInfo {
36    pub id: u64,
37    pub cortical_id: String,
38    pub cortical_idx: u32,
39    pub coordinates: (u32, u32, u32),
40    pub properties: HashMap<String, serde_json::Value>,
41}
42
43/// Parameters for creating a neuron
44#[derive(Debug, Clone, Serialize, Deserialize)]
45pub struct CreateNeuronParams {
46    pub cortical_id: String,
47    pub coordinates: (u32, u32, u32),
48    pub properties: Option<HashMap<String, serde_json::Value>>,
49}
50
51// ============================================================================
52// CORTICAL AREA DTOs
53// ============================================================================
54
55/// Information about a cortical area
56/// This structure matches the Python FEAGI API for full compatibility
57#[derive(Debug, Clone, Serialize, Deserialize)]
58pub struct CorticalAreaInfo {
59    pub cortical_id: String,
60    pub cortical_id_s: String, // Human-readable ASCII string (e.g., "___power" instead of "X19fcG93ZXI=")
61    pub cortical_idx: u32,
62    #[serde(rename = "cortical_name", alias = "name")]
63    pub name: String,
64    #[serde(rename = "cortical_dimensions", alias = "dimensions")]
65    pub dimensions: (usize, usize, usize),
66    #[serde(rename = "coordinates_3d", alias = "position")]
67    pub position: (i32, i32, i32),
68    pub area_type: String,      // "Sensory", "Motor", "Memory", "Custom"
69    pub cortical_group: String, // "IPU", "OPU", "CORE", "CUSTOM", "MEMORY" - uppercase classification
70    /// Explicit cortical type classification: "sensory", "motor", "memory", "custom", "core"
71    /// This field provides a clear, standardized type indicator that BV can rely on
72    /// instead of parsing cortical_group or other heuristics.
73    pub cortical_type: String,
74    pub neuron_count: usize,
75    pub synapse_count: usize,
76    /// Total number of incoming synapses targeting neurons in this area.
77    pub incoming_synapse_count: usize,
78    /// Total number of outgoing synapses originating from neurons in this area.
79    pub outgoing_synapse_count: usize,
80    pub visible: bool,
81    #[serde(
82        rename = "cortical_sub_group",
83        alias = "sub_group",
84        skip_serializing_if = "Option::is_none"
85    )]
86    pub sub_group: Option<String>,
87    pub neurons_per_voxel: u32,
88    #[serde(rename = "neuron_post_synaptic_potential")]
89    pub postsynaptic_current: f64,
90    #[serde(rename = "neuron_post_synaptic_potential_max")]
91    pub postsynaptic_current_max: f64,
92    #[serde(rename = "neuron_plasticity_constant")]
93    pub plasticity_constant: f64,
94    #[serde(rename = "neuron_degeneracy_coefficient")]
95    pub degeneration: f64,
96    #[serde(rename = "neuron_psp_uniform_distribution")]
97    pub psp_uniform_distribution: bool,
98    #[serde(rename = "neuron_mp_driven_psp")]
99    pub mp_driven_psp: bool,
100    #[serde(rename = "neuron_fire_threshold")]
101    pub firing_threshold: f64,
102    #[serde(rename = "neuron_fire_threshold_increment")]
103    pub firing_threshold_increment: [f64; 3],
104    #[serde(rename = "neuron_firing_threshold_limit")]
105    pub firing_threshold_limit: f64,
106    #[serde(rename = "neuron_consecutive_fire_count")]
107    pub consecutive_fire_count: u32,
108    #[serde(rename = "neuron_snooze_period")]
109    pub snooze_period: u32,
110    #[serde(rename = "neuron_refractory_period")]
111    pub refractory_period: u32,
112    #[serde(rename = "neuron_leak_coefficient")]
113    pub leak_coefficient: f64,
114    #[serde(rename = "neuron_leak_variability")]
115    pub leak_variability: f64,
116    #[serde(rename = "neuron_mp_charge_accumulation")]
117    pub mp_charge_accumulation: bool,
118    #[serde(rename = "neuron_excitability")]
119    pub neuron_excitability: f64,
120    #[serde(rename = "neuron_burst_engine_active")]
121    pub burst_engine_active: bool,
122    #[serde(rename = "neuron_init_lifespan")]
123    pub init_lifespan: u32,
124    #[serde(rename = "neuron_lifespan_growth_rate")]
125    pub lifespan_growth_rate: f64,
126    #[serde(rename = "neuron_longterm_mem_threshold")]
127    pub longterm_mem_threshold: u32,
128    /// Memory pattern detection lookback depth for memory cortical areas.
129    /// Omitted for non-memory areas.
130    #[serde(rename = "temporal_depth", skip_serializing_if = "Option::is_none")]
131    pub temporal_depth: Option<u32>,
132    pub properties: HashMap<String, serde_json::Value>,
133
134    // IPU/OPU-specific decoded cortical ID fields (optional, only populated for IPU/OPU)
135    /// 4-character cortical subtype (e.g., "isvi", "imot", "ibat") - only for IPU/OPU
136    #[serde(skip_serializing_if = "Option::is_none")]
137    pub cortical_subtype: Option<String>,
138
139    /// Encoding type: "Absolute" or "Incremental" - only for IPU/OPU
140    #[serde(skip_serializing_if = "Option::is_none")]
141    pub encoding_type: Option<String>,
142
143    /// Encoding format: "Linear" or "Fractional" - only for IPU/OPU
144    #[serde(skip_serializing_if = "Option::is_none")]
145    pub encoding_format: Option<String>,
146
147    /// Unit ID (0, 1, 2, ...) - only for IPU/OPU
148    #[serde(skip_serializing_if = "Option::is_none")]
149    pub unit_id: Option<u8>,
150
151    /// Group ID (0, 1, 2, ...) - only for IPU/OPU
152    #[serde(skip_serializing_if = "Option::is_none")]
153    pub group_id: Option<u8>,
154
155    /// IO coding signage (e.g., "Percentage Signed", "Percentage Unsigned")
156    #[serde(skip_serializing_if = "Option::is_none")]
157    pub coding_signage: Option<String>,
158
159    /// IO coding behavior ("Absolute" or "Incremental")
160    #[serde(skip_serializing_if = "Option::is_none")]
161    pub coding_behavior: Option<String>,
162
163    /// IO coding type ("Linear" or "Fractional")
164    #[serde(skip_serializing_if = "Option::is_none")]
165    pub coding_type: Option<String>,
166
167    /// Allowed IO coding options for this cortical unit.
168    #[serde(skip_serializing_if = "Option::is_none")]
169    pub coding_options: Option<IOCodingOptions>,
170
171    /// Parent brain region ID (UUID string) - which brain region this cortical area belongs to
172    /// This is required by Brain Visualizer to correctly place cortical areas in the 3D scene
173    #[serde(skip_serializing_if = "Option::is_none")]
174    pub parent_region_id: Option<String>,
175
176    /// Number of devices/channels for IPU/OPU areas (e.g., number of cameras for vision)
177    /// This is the total device count that was specified when creating the area
178    #[serde(skip_serializing_if = "Option::is_none")]
179    pub dev_count: Option<usize>,
180
181    /// Per-device/per-channel dimensions for IPU/OPU areas
182    /// For a multi-channel area, this represents the dimensions of a single channel
183    /// The total width is: cortical_dimensions_per_device.width * dev_count
184    #[serde(skip_serializing_if = "Option::is_none")]
185    pub cortical_dimensions_per_device: Option<(usize, usize, usize)>,
186
187    /// Visualization voxel granularity for large-area rendering (x, y, z)
188    /// This defines the voxel chunk size used for aggregation when rendering
189    /// very large cortical areas (>1M neurons). BV uses this to render spatial patterns
190    /// at a coarser resolution to maintain performance.
191    /// Example: For 512×512×22 area, granularity might be (16, 16, 16) → 32×32×2 = 2,048 chunks
192    /// Default is (1, 1, 1) - always serialized so BV knows the value
193    pub visualization_voxel_granularity: Option<(u32, u32, u32)>,
194}
195
196/// Parameters for creating a cortical area
197#[derive(Debug, Clone, Serialize, Deserialize)]
198pub struct CreateCorticalAreaParams {
199    pub cortical_id: String,
200    pub name: String,
201    pub dimensions: (usize, usize, usize),
202    pub position: (i32, i32, i32),
203    pub area_type: String,
204    pub visible: Option<bool>,
205    pub sub_group: Option<String>,
206    pub neurons_per_voxel: Option<u32>,
207    pub postsynaptic_current: Option<f64>,
208    pub plasticity_constant: Option<f64>,
209    pub degeneration: Option<f64>,
210    pub psp_uniform_distribution: Option<bool>,
211    pub firing_threshold_increment: Option<f64>,
212    pub firing_threshold_limit: Option<f64>,
213    pub consecutive_fire_count: Option<u32>,
214    pub snooze_period: Option<u32>,
215    pub refractory_period: Option<u32>,
216    pub leak_coefficient: Option<f64>,
217    pub leak_variability: Option<f64>,
218    pub burst_engine_active: Option<bool>,
219    pub properties: Option<HashMap<String, serde_json::Value>>,
220}
221
222/// Parameters for updating a cortical area
223#[derive(Debug, Clone, Serialize, Deserialize)]
224pub struct UpdateCorticalAreaParams {
225    pub name: Option<String>,
226    pub position: Option<(i32, i32, i32)>,
227    pub dimensions: Option<(usize, usize, usize)>,
228    pub area_type: Option<String>,
229    pub visible: Option<bool>,
230    pub postsynaptic_current: Option<f64>,
231    pub plasticity_constant: Option<f64>,
232    pub degeneration: Option<f64>,
233    pub psp_uniform_distribution: Option<bool>,
234    pub firing_threshold_increment: Option<f64>,
235    pub firing_threshold_limit: Option<f64>,
236    pub consecutive_fire_count: Option<u32>,
237    pub snooze_period: Option<u32>,
238    pub refractory_period: Option<u32>,
239    pub leak_coefficient: Option<f64>,
240    pub leak_variability: Option<f64>,
241    pub burst_engine_active: Option<bool>,
242}
243
244// ============================================================================
245// BRAIN REGION DTOs
246// ============================================================================
247
248/// Information about a brain region
249#[derive(Debug, Clone, Serialize, Deserialize)]
250pub struct BrainRegionInfo {
251    pub region_id: String,
252    pub name: String,
253    pub region_type: String, // "Sensory", "Motor", "Association", "Custom"
254    pub parent_id: Option<String>,
255    pub cortical_areas: Vec<String>,
256    pub child_regions: Vec<String>,
257    pub properties: HashMap<String, serde_json::Value>,
258}
259
260/// Parameters for creating a brain region
261#[derive(Debug, Clone, Serialize, Deserialize)]
262pub struct CreateBrainRegionParams {
263    pub region_id: String,
264    pub name: String,
265    pub region_type: String,
266    pub parent_id: Option<String>,
267    pub properties: Option<HashMap<String, serde_json::Value>>,
268}
269
270// ============================================================================
271// MORPHOLOGY DTOs
272// ============================================================================
273
274/// Information about a morphology
275#[derive(Debug, Clone, Serialize, Deserialize)]
276pub struct MorphologyInfo {
277    pub morphology_type: String,
278    pub class: String,
279    pub parameters: serde_json::Value,
280}
281
282// ============================================================================
283// GENOME DTOs
284// ============================================================================
285
286/// Information about a genome
287#[derive(Debug, Clone, Serialize, Deserialize)]
288pub struct GenomeInfo {
289    pub genome_id: String,
290    pub genome_title: String,
291    pub version: String,
292    pub cortical_area_count: usize,
293    pub brain_region_count: usize,
294    pub simulation_timestep: f64, // Simulation timestep in seconds from physiology
295    pub genome_num: Option<i32>,  // Genome version/generation number
296    pub genome_timestamp: Option<i64>, // Unix timestamp when genome was loaded/created
297}
298
299/// Parameters for loading a genome
300#[derive(Debug, Clone, Serialize, Deserialize)]
301pub struct LoadGenomeParams {
302    pub json_str: String,
303}
304
305/// Parameters for saving a genome
306#[derive(Debug, Clone, Serialize, Deserialize)]
307pub struct SaveGenomeParams {
308    pub genome_id: Option<String>,
309    pub genome_title: Option<String>,
310}
311
312// ============================================================================
313// CONNECTIVITY DTOs
314// ============================================================================
315
316/// Information about a synapse
317#[derive(Debug, Clone, Serialize, Deserialize)]
318pub struct SynapseInfo {
319    pub source_neuron: u64,
320    pub target_neuron: u64,
321    pub weight: u8,
322    pub psp: u8,
323    pub synapse_type: String, // "Excitatory" or "Inhibitory"
324}
325
326/// Parameters for creating a synapse
327#[derive(Debug, Clone, Serialize, Deserialize)]
328pub struct CreateSynapseParams {
329    pub source_neuron: u64,
330    pub target_neuron: u64,
331    pub weight: u8,
332    pub psp: u8,
333    pub synapse_type: String,
334}
335
336// ============================================================================
337// ANALYTICS DTOs
338// ============================================================================
339
340/// Statistics for a cortical area
341#[derive(Debug, Clone, Serialize, Deserialize)]
342pub struct CorticalAreaStats {
343    pub cortical_id: String,
344    pub neuron_count: usize,
345    pub synapse_count: usize,
346    pub density: f32,
347    pub populated: bool,
348}
349
350/// Connectivity statistics between two areas
351#[derive(Debug, Clone, Serialize, Deserialize)]
352pub struct ConnectivityStats {
353    pub source_area: String,
354    pub target_area: String,
355    pub synapse_count: usize,
356    pub avg_weight: f32,
357    pub excitatory_count: usize,
358    pub inhibitory_count: usize,
359}
360
361/// System health information
362#[derive(Debug, Clone, Serialize, Deserialize)]
363pub struct SystemHealth {
364    pub burst_engine_active: bool,
365    pub brain_readiness: bool,
366    pub neuron_count: usize,
367    pub neuron_capacity: usize,
368    pub synapse_capacity: usize,
369    pub cortical_area_count: usize,
370    pub burst_count: u64,
371}
372
373// ============================================================================
374// RUNTIME DTOs
375// ============================================================================
376
377/// Runtime status information
378#[derive(Debug, Clone, Serialize, Deserialize)]
379pub struct RuntimeStatus {
380    /// Whether the burst engine is running
381    pub is_running: bool,
382
383    /// Whether the burst engine is paused
384    pub is_paused: bool,
385
386    /// Current burst frequency (Hz)
387    pub frequency_hz: f64,
388
389    /// Total burst count since start
390    pub burst_count: u64,
391
392    /// Current burst rate (bursts per second, measured)
393    pub current_rate_hz: f64,
394
395    /// Total neurons fired in last burst
396    pub last_burst_neuron_count: usize,
397
398    /// Average processing time per burst (milliseconds)
399    pub avg_burst_time_ms: f64,
400}
401
402// ============================================================================
403// SYSTEM SERVICE DTOs
404// ============================================================================
405
406/// Component health status
407#[derive(Debug, Clone, Serialize, Deserialize)]
408pub struct ComponentHealth {
409    pub name: String,
410    pub status: String, // "healthy", "degraded", "unhealthy"
411    pub message: Option<String>,
412}
413
414/// Overall system health
415#[derive(Debug, Clone, Serialize, Deserialize)]
416pub struct HealthStatus {
417    pub overall_status: String, // "healthy", "degraded", "unhealthy"
418    pub components: Vec<ComponentHealth>,
419    pub timestamp: String, // ISO 8601 timestamp
420}
421
422/// Comprehensive system status
423#[derive(Debug, Clone, Serialize, Deserialize)]
424pub struct SystemStatus {
425    pub is_initialized: bool,
426    pub burst_engine_running: bool,
427    pub burst_count: u64,
428    pub neuron_count: usize,
429    pub synapse_count: usize,
430    pub cortical_area_count: usize,
431    pub brain_region_count: usize,
432    pub uptime_seconds: u64,
433    pub current_burst_rate_hz: f64,
434    pub avg_burst_time_ms: f64,
435}
436
437/// Version information for FEAGI runtime
438/// Contains versions of all crates compiled into the current binary
439/// This is populated by the application (e.g., feagi-rust) at startup
440#[derive(Debug, Clone, Serialize, Deserialize, Default)]
441pub struct VersionInfo {
442    /// Map of crate name to version (e.g., "feagi_brain_development" -> "2.0.0")
443    /// Only includes crates actually linked into this binary
444    pub crates: std::collections::HashMap<String, String>,
445
446    /// Build timestamp (if available)
447    pub build_timestamp: String,
448
449    /// Rust compiler version used
450    pub rust_version: String,
451}
452
453/// Runtime statistics
454#[derive(Debug, Clone, Serialize, Deserialize)]
455pub struct RuntimeStats {
456    pub total_bursts: u64,
457    pub total_neurons_fired: u64,
458    pub total_processing_time_ms: u64,
459    pub avg_burst_time_ms: f64,
460    pub avg_neurons_per_burst: f64,
461    pub current_rate_hz: f64,
462    pub peak_rate_hz: f64,
463    pub uptime_seconds: u64,
464}
465
466/// Memory usage information
467#[derive(Debug, Clone, Serialize, Deserialize)]
468pub struct MemoryUsage {
469    pub npu_neurons_bytes: usize,
470    pub npu_synapses_bytes: usize,
471    pub npu_total_bytes: usize,
472    pub connectome_metadata_bytes: usize,
473    pub total_allocated_bytes: usize,
474    pub system_total_bytes: usize,
475    pub system_available_bytes: usize,
476}
477
478/// Capacity information
479#[derive(Debug, Clone, Serialize, Deserialize)]
480pub struct CapacityInfo {
481    pub current_neurons: usize,
482    pub max_neurons: usize,
483    pub neuron_utilization_percent: f64,
484    pub current_synapses: usize,
485    pub max_synapses: usize,
486    pub synapse_utilization_percent: f64,
487    pub current_cortical_areas: usize,
488    pub max_cortical_areas: usize,
489}
feagi_services/types/dtos.rs

feagi_services/types/
dtos.rs
