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 = "std")]
91pub mod genome;
92#[cfg(feature = "std")]
93pub mod impls;
94pub mod traits;
95pub mod types;
96
97// Re-export main API
98pub use traits::{
99    AnalyticsService, ConnectomeService, GenomeService, NeuronService, RuntimeService,
100    SnapshotCreateOptions, SnapshotMetadata, SnapshotService,
101};
102
103pub use types::{
104    // Agent registry types
105    agent_registry::{
106        AgentCapabilities, AgentInfo, AgentRegistry, AgentTransport, AgentType, MotorCapability,
107        SensoryCapability, VisionCapability, VisualizationCapability,
108    },
109    // Registration DTOs
110    registration::{
111        AreaStatus, CorticalAreaAvailability, CorticalAreaStatus, RegistrationRequest,
112        RegistrationResponse, TransportConfig,
113    },
114    // DTOs
115    BrainRegionInfo,
116    ConnectivityStats,
117    CorticalAreaInfo,
118    CorticalAreaStats,
119    CreateBrainRegionParams,
120    CreateCorticalAreaParams,
121    CreateNeuronParams,
122    CreateSynapseParams,
123    GenomeInfo,
124    LoadGenomeParams,
125    NeuronInfo,
126    RuntimeStatus,
127    SaveGenomeParams,
128    // Errors
129    ServiceError,
130    ServiceResult,
131    SynapseInfo,
132    SystemHealth,
133    UpdateCorticalAreaParams,
134};
135
136// Re-export implementations (optional - adapters can use their own)
137#[cfg(feature = "std")]
138pub use impls::{
139    AnalyticsServiceImpl, ConnectomeServiceImpl, GenomeServiceImpl, NeuronServiceImpl,
140    RuntimeServiceImpl, SnapshotServiceImpl,
141};
142
143/// Version of this crate (for feagi-rust version reporting)
144pub const VERSION: &str = env!("CARGO_PKG_VERSION");
feagi_services/lib.rs

feagi_services/
lib.rs
