feagi_api/v1/
cortical_area_dtos.rs

1// Copyright 2025 Neuraville Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4// Cortical Area DTOs for V1 API
5//
6// These DTOs must match Python FastAPI response structures exactly.
7
8use serde::{Deserialize, Serialize};
9use utoipa::ToSchema;
10
11/// Detailed cortical type information (Phase 5)
12///
13/// Provides rich type information from the new CorticalAreaType system.
14/// This enables clients to understand data encoding, frame handling, and more.
15#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
16#[schema(example = json!({
17    "category": "IPU",
18    "data_type": "CartesianPlane",
19    "frame_handling": "Absolute",
20    "encoding_details": {
21        "positioning": "Linear",
22        "signed": false
23    }
24}))]
25pub struct CorticalTypeInfo {
26    /// High-level category: IPU, OPU, CORE, MEMORY, CUSTOM
27    pub category: String,
28
29    /// Data type: CartesianPlane, Percentage, SignedPercentage, Misc, etc.
30    #[serde(skip_serializing_if = "Option::is_none")]
31    pub data_type: Option<String>,
32
33    /// Frame change handling: Absolute or Incremental
34    #[serde(skip_serializing_if = "Option::is_none")]
35    pub frame_handling: Option<String>,
36
37    /// Additional encoding details (optional)
38    #[serde(skip_serializing_if = "Option::is_none")]
39    pub encoding_details: Option<serde_json::Value>,
40}
41
42/// Cortical area information (summary)
43#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
44#[schema(example = json!({
45    "cortical_id": "v1",
46    "cortical_name": "Primary Visual Cortex",
47    "cortical_group": "vision",
48    "coordinates_3d": {
49        "x": 0,
50        "y": 0,
51        "z": 0
52    },
53    "cortical_dimensions": {
54        "x": 10,
55        "y": 10,
56        "z": 10
57    },
58    "neuron_count": 1000,
59    "cortical_visibility": true,
60    "cortical_type_info": {
61        "category": "IPU",
62        "data_type": "CartesianPlane",
63        "frame_handling": "Absolute"
64    }
65}))]
66pub struct CorticalAreaSummary {
67    /// Cortical area ID
68    pub cortical_id: String,
69
70    /// Human-readable name
71    pub cortical_name: String,
72
73    /// Functional group (vision, motor, memory, etc.)
74    pub cortical_group: String,
75
76    /// 3D coordinates in brain space
77    pub coordinates_3d: Coordinates3D,
78
79    /// Dimensions of the cortical area
80    pub cortical_dimensions: Dimensions3D,
81
82    /// Number of neurons in this area
83    pub neuron_count: usize,
84
85    /// Is this area visible in visualization?
86    pub cortical_visibility: bool,
87
88    /// Phase 5: Detailed cortical type information (optional for backward compatibility)
89    #[serde(skip_serializing_if = "Option::is_none")]
90    pub cortical_type_info: Option<CorticalTypeInfo>,
91}
92
93/// Detailed cortical area information
94#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
95#[schema(example = json!({
96    "cortical_id": "v1",
97    "cortical_name": "Primary Visual Cortex",
98    "cortical_group": "vision",
99    "coordinates_3d": {
100        "x": 0,
101        "y": 0,
102        "z": 0
103    },
104    "cortical_dimensions": {
105        "x": 10,
106        "y": 10,
107        "z": 10
108    },
109    "neuron_count": 1000,
110    "synapse_count": 5000,
111    "incoming_synapse_count": 2500,
112    "outgoing_synapse_count": 2500,
113    "cortical_visibility": true,
114    "cortical_sub_group_name": "visual_input",
115    "cortical_neuron_per_vox_count": 1,
116    "postsynaptic_current": 1.0,
117    "plasticity_constant": 0.5,
118    "degeneration": 0.0,
119    "psp_uniform_distribution": false,
120    "firing_threshold_increment": 0.1,
121    "firing_threshold_limit": 10.0,
122    "consecutive_fire_count": 3,
123    "snooze_period": 5,
124    "refractory_period": 2,
125    "leak_coefficient": 0.01,
126    "leak_variability": 0.0,
127    "burst_engine_activation": true
128}))]
129pub struct CorticalAreaDetail {
130    /// Cortical area ID
131    pub cortical_id: String,
132
133    /// Human-readable name
134    pub cortical_name: String,
135
136    /// Functional group
137    pub cortical_group: String,
138
139    /// 3D coordinates
140    pub coordinates_3d: Coordinates3D,
141
142    /// Dimensions
143    pub cortical_dimensions: Dimensions3D,
144
145    /// Number of neurons
146    pub neuron_count: usize,
147
148    /// Number of synapses
149    pub synapse_count: usize,
150
151    /// Number of incoming synapses
152    pub incoming_synapse_count: usize,
153
154    /// Number of outgoing synapses
155    pub outgoing_synapse_count: usize,
156
157    /// Visibility flag
158    pub cortical_visibility: bool,
159
160    /// Sub-group name
161    pub cortical_sub_group_name: String,
162
163    /// Neurons per voxel
164    pub cortical_neuron_per_vox_count: u32,
165
166    /// Postsynaptic current
167    pub postsynaptic_current: f64,
168
169    /// Plasticity constant
170    pub plasticity_constant: f64,
171
172    /// Degeneration rate
173    pub degeneration: f64,
174
175    /// PSP uniform distribution
176    pub psp_uniform_distribution: bool,
177
178    /// Firing threshold increment
179    pub firing_threshold_increment: f64,
180
181    /// Firing threshold limit
182    pub firing_threshold_limit: f64,
183
184    /// Consecutive fire count
185    pub consecutive_fire_count: u32,
186
187    /// Snooze period
188    pub snooze_period: u32,
189
190    /// Refractory period
191    pub refractory_period: u32,
192
193    /// Leak coefficient
194    pub leak_coefficient: f64,
195
196    /// Leak variability
197    pub leak_variability: f64,
198
199    /// Burst engine activation
200    pub burst_engine_activation: bool,
201
202    /// Phase 5: Detailed cortical type information (optional for backward compatibility)
203    #[serde(skip_serializing_if = "Option::is_none")]
204    pub cortical_type_info: Option<CorticalTypeInfo>,
205}
206
207/// Create cortical area request
208#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
209pub struct CreateCorticalAreaRequest {
210    /// Cortical area ID
211    pub cortical_id: String,
212
213    /// Human-readable name
214    pub cortical_name: String,
215
216    /// Functional group
217    pub cortical_group: String,
218
219    /// 3D coordinates
220    pub coordinates_3d: Coordinates3D,
221
222    /// Dimensions
223    pub cortical_dimensions: Dimensions3D,
224
225    /// Optional: Visibility (default: true)
226    #[serde(default = "default_visibility")]
227    pub cortical_visibility: bool,
228
229    /// Optional: Sub-group name
230    #[serde(default)]
231    pub cortical_sub_group_name: Option<String>,
232
233    /// Optional: Neurons per voxel (default: 1)
234    #[serde(default = "default_neurons_per_vox")]
235    pub cortical_neuron_per_vox_count: u32,
236
237    /// Optional: Postsynaptic current (default: 1.0)
238    #[serde(default = "default_postsynaptic_current")]
239    pub postsynaptic_current: f64,
240
241    /// Optional: Plasticity constant (default: 0.5)
242    #[serde(default = "default_plasticity_constant")]
243    pub plasticity_constant: f64,
244}
245
246/// Update cortical area request
247#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
248pub struct UpdateCorticalAreaRequest {
249    /// Optional: New name
250    pub cortical_name: Option<String>,
251
252    /// Optional: New group
253    pub cortical_group: Option<String>,
254
255    /// Optional: New coordinates
256    pub coordinates_3d: Option<Coordinates3D>,
257
258    /// Optional: New dimensions
259    pub cortical_dimensions: Option<Dimensions3D>,
260
261    /// Optional: Visibility
262    pub cortical_visibility: Option<bool>,
263
264    /// Optional: Postsynaptic current
265    pub postsynaptic_current: Option<f64>,
266
267    /// Optional: Plasticity constant
268    pub plasticity_constant: Option<f64>,
269}
270
271/// 3D coordinates
272#[derive(Debug, Clone, Copy, Serialize, Deserialize, ToSchema)]
273pub struct Coordinates3D {
274    pub x: i32,
275    pub y: i32,
276    pub z: i32,
277}
278
279/// 3D dimensions
280#[derive(Debug, Clone, Copy, Serialize, Deserialize, ToSchema)]
281pub struct Dimensions3D {
282    pub x: u32,
283    pub y: u32,
284    pub z: u32,
285}
286
287/// List cortical areas response
288#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
289pub struct CorticalAreaListResponse {
290    /// List of cortical areas
291    pub cortical_areas: Vec<CorticalAreaSummary>,
292
293    /// Total count
294    pub total_count: usize,
295}
296
297// Default values for optional fields
298fn default_visibility() -> bool {
299    true
300}
301
302fn default_neurons_per_vox() -> u32 {
303    1
304}
305
306fn default_postsynaptic_current() -> f64 {
307    1.0
308}
309
310fn default_plasticity_constant() -> f64 {
311    0.5
312}
feagi_api/v1/cortical_area_dtos.rs

feagi_api/v1/
cortical_area_dtos.rs
