feagi_api/v1/
agent_dtos.rs

1// Copyright 2025 Neuraville Inc.
2// Licensed under the Apache License, Version 2.0
3
4//! Agent API DTOs - Exact port from Python schemas
5
6use serde::{Deserialize, Serialize};
7use std::collections::HashMap;
8use utoipa::ToSchema;
9
10/// Agent registration request
11#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
12pub struct AgentRegistrationRequest {
13    /// Type of agent (e.g., "brain_visualizer", "video_agent")
14    pub agent_type: String,
15
16    /// Unique identifier for the agent
17    pub agent_id: String,
18
19    /// Port the agent is listening on for data
20    pub agent_data_port: u16,
21
22    /// Version of the agent software
23    pub agent_version: String,
24
25    /// Version of the controller
26    pub controller_version: String,
27
28    /// Agent capabilities (sensory, motor, visualization, etc.)
29    pub capabilities: HashMap<String, serde_json::Value>,
30
31    /// Optional: Agent IP address (extracted from request if not provided)
32    #[serde(skip_serializing_if = "Option::is_none")]
33    pub agent_ip: Option<String>,
34
35    /// Optional: Additional metadata
36    #[serde(skip_serializing_if = "Option::is_none")]
37    pub metadata: Option<HashMap<String, serde_json::Value>>,
38
39    /// Optional: Transport the agent chose to use ("zmq", "websocket", "shm", etc.)
40    #[serde(skip_serializing_if = "Option::is_none")]
41    pub chosen_transport: Option<String>,
42}
43
44/// Transport configuration for an agent (from PNS)
45#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
46pub struct TransportConfig {
47    pub transport_type: String,
48    pub enabled: bool,
49    pub ports: HashMap<String, u16>,
50    pub host: String,
51}
52
53/// Agent registration response
54#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
55pub struct AgentRegistrationResponse {
56    pub status: String,
57    pub message: String,
58    pub success: bool,
59
60    #[serde(skip_serializing_if = "Option::is_none")]
61    pub transport: Option<HashMap<String, serde_json::Value>>,
62
63    #[serde(skip_serializing_if = "Option::is_none")]
64    pub rates: Option<HashMap<String, HashMap<String, f64>>>,
65
66    // FEAGI 2.0: Multi-transport support
67    #[serde(skip_serializing_if = "Option::is_none")]
68    pub transports: Option<Vec<TransportConfig>>,
69
70    #[serde(skip_serializing_if = "Option::is_none")]
71    pub recommended_transport: Option<String>,
72
73    #[serde(skip_serializing_if = "Option::is_none")]
74    pub zmq_ports: Option<HashMap<String, u16>>,
75
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub shm_paths: Option<HashMap<String, String>>,
78
79    /// Cortical area availability status for agent operations
80    pub cortical_areas: serde_json::Value,
81}
82
83/// Heartbeat request
84#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
85pub struct HeartbeatRequest {
86    pub agent_id: String,
87}
88
89/// Heartbeat response
90#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
91pub struct HeartbeatResponse {
92    pub message: String,
93    pub success: bool,
94}
95
96/// Agent list response
97#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
98pub struct AgentListResponse {
99    /// List of agent IDs
100    #[serde(flatten)]
101    pub agent_ids: Vec<String>,
102}
103
104/// Agent properties response
105#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
106pub struct AgentPropertiesResponse {
107    pub agent_type: String,
108    pub agent_ip: String,
109    pub agent_data_port: u16,
110    pub agent_router_address: String,
111    pub agent_version: String,
112    pub controller_version: String,
113    pub capabilities: HashMap<String, serde_json::Value>,
114    #[serde(skip_serializing_if = "Option::is_none")]
115    pub chosen_transport: Option<String>,
116}
117
118/// Agent deregistration request
119#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
120pub struct AgentDeregistrationRequest {
121    pub agent_id: String,
122}
123
124/// Success response
125#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
126pub struct SuccessResponse {
127    pub message: String,
128    #[serde(skip_serializing_if = "Option::is_none")]
129    pub success: Option<bool>,
130}
131
132/// Manual stimulation request
133#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
134pub struct ManualStimulationRequest {
135    /// Map of cortical area IDs to lists of coordinates [[x, y, z], ...]
136    pub stimulation_payload: HashMap<String, Vec<Vec<i32>>>,
137}
138
139/// Manual stimulation response
140#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
141pub struct ManualStimulationResponse {
142    pub success: bool,
143    pub total_coordinates: usize,
144    pub successful_areas: usize,
145    pub failed_areas: Vec<String>,
146    #[serde(skip_serializing_if = "Option::is_none")]
147    pub error: Option<String>,
148}
149
150/// Device registration export response
151///
152/// Contains the complete device registration configuration including
153/// sensor and motor device registrations, encoder/decoder properties,
154/// and feedback configurations.
155#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
156pub struct DeviceRegistrationExportResponse {
157    /// Device registration configuration as JSON
158    /// This matches the format from ConnectorAgent::export_device_registrations_as_config_json
159    pub device_registrations: serde_json::Value,
160    /// Agent ID this configuration belongs to
161    pub agent_id: String,
162}
163
164/// Device registration import request
165///
166/// Contains the device registration configuration to import.
167/// This will replace all existing device registrations for the agent.
168#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
169pub struct DeviceRegistrationImportRequest {
170    /// Device registration configuration as JSON
171    /// This matches the format expected by ConnectorAgent::import_device_registrations_as_config_json
172    pub device_registrations: serde_json::Value,
173}
174
175/// Device registration import response
176#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
177pub struct DeviceRegistrationImportResponse {
178    pub success: bool,
179    pub message: String,
180    pub agent_id: String,
181}
feagi_api/v1/agent_dtos.rs

feagi_api/v1/
agent_dtos.rs
