feagi_services/
lib.rs

1// Copyright 2025 Neuraville Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4/*!
5# FEAGI Service Layer
6
7The stable application boundary for FEAGI - defines transport-agnostic
8service interfaces that can be used by any adapter (REST API, ZMQ, embedded).
9
10## Architecture
11
12```text
13┌─────────────────────────────────────────────────────────────────┐
14│                    TRANSPORT ADAPTERS                            │
15│  Axum/REST, ZMQ Control, Embedded I2C, etc.                     │
16└────────────────────────────┬────────────────────────────────────┘
17                             ↓
18┌─────────────────────────────────────────────────────────────────┐
19│              SERVICE LAYER (This Crate)                          │
20│  • NeuronService      - Neuron CRUD operations                  │
21│  • GenomeService      - Genome load/save                        │
22│  • ConnectomeService  - Cortical area & brain region management │
23│  • AnalyticsService   - Statistics & system health              │
24└────────────────────────────┬────────────────────────────────────┘
25                             ↓
26┌─────────────────────────────────────────────────────────────────┐
27│                   DOMAIN LAYER                                   │
28│  feagi-bdu, feagi-evo, feagi-burst-engine, feagi-types          │
29└─────────────────────────────────────────────────────────────────┘
30```
31
32## Design Principles
33
341. **Transport-Agnostic**: Services know nothing about HTTP, ZMQ, or I2C
352. **Stable Contracts**: Trait interfaces don't change when backend changes
363. **Async by Default**: All services are async (can be compiled out for embedded)
374. **Error Translation**: Backend errors are translated to transport-agnostic `ServiceError`
385. **DTO-Based**: All parameters and returns use transport-agnostic DTOs
39
40## Usage
41
42### For Adapter Implementers
43
44Adapters depend on service traits, not implementations:
45
46```rust,ignore
47use feagi_services::{NeuronService, ServiceResult, CreateNeuronParams};
48
49async fn handle_http_request(
50    service: &dyn NeuronService,
51    req: HttpRequest
52) -> HttpResponse {
53    // 1. Parse HTTP request to DTO
54    let params = CreateNeuronParams { ... };
55
56    // 2. Call service (transport-agnostic)
57    let result = service.create_neuron(params).await?;
58
59    // 3. Convert DTO to HTTP response
60    HttpResponse::ok(result)
61}
62```
63
64### For Backend Implementers
65
66Implementations use domain logic (BDU, NPU, Evo):
67
68```rust,ignore
69use feagi_services::{NeuronService, ServiceResult};
70use feagi_brain_development::ConnectomeManager;
71
72struct NeuronServiceImpl {
73    connectome: Arc<ConnectomeManager>,
74}
75
76#[async_trait]
77impl NeuronService for NeuronServiceImpl {
78    async fn create_neuron(&self, params: CreateNeuronParams) -> ServiceResult<NeuronInfo> {
79        // Delegate to domain logic
80        self.connectome.create_neuron(...)?;
81        Ok(NeuronInfo { ... })
82    }
83}
84```
85
86Copyright 2025 Neuraville Inc.
87Licensed under the Apache License, Version 2.0
88*/
89
90#[cfg(feature = "connectome-serialization")]
91pub mod connectome;
92#[cfg(feature = "std")]
93pub mod genome;
94#[cfg(feature = "std")]
95pub mod impls;
96pub mod traits;
97pub mod types;
98
99// Re-export main API
100pub use traits::{
101    AnalyticsService, ConnectomeService, GenomeService, NeuronService, RuntimeService,
102    SnapshotCreateOptions, SnapshotMetadata, SnapshotService,
103};
104
105pub use types::{
106    // Agent registry types
107    agent_registry::{
108        AgentCapabilities, AgentInfo, AgentRegistry, AgentTransport, AgentType, MotorCapability,
109        SensoryCapability, VisionCapability, VisualizationCapability,
110    },
111    // Registration DTOs
112    registration::{
113        AreaStatus, CorticalAreaAvailability, CorticalAreaStatus, RegistrationRequest,
114        RegistrationResponse, TransportConfig,
115    },
116    // DTOs
117    BrainRegionInfo,
118    ConnectivityStats,
119    CorticalAreaInfo,
120    CorticalAreaStats,
121    CreateBrainRegionParams,
122    CreateCorticalAreaParams,
123    CreateNeuronParams,
124    CreateSynapseParams,
125    GenomeInfo,
126    LoadGenomeParams,
127    NeuronInfo,
128    RuntimeStatus,
129    SaveGenomeParams,
130    // Errors
131    ServiceError,
132    ServiceResult,
133    SynapseInfo,
134    SystemHealth,
135    UpdateCorticalAreaParams,
136};
137
138// Re-export cortical area helpers for adapter crates.
139pub use feagi_brain_development::models::CorticalAreaExt;
140
141// Re-export implementations (optional - adapters can use their own)
142#[cfg(feature = "std")]
143pub use impls::{
144    AnalyticsServiceImpl, ConnectomeServiceImpl, GenomeServiceImpl, NeuronServiceImpl,
145    RuntimeServiceImpl, SnapshotServiceImpl,
146};
147
148/// Version of this crate (for feagi-rust version reporting)
149pub const VERSION: &str = env!("CARGO_PKG_VERSION");
feagi_services/lib.rs

feagi_services/
lib.rs
