Crate feagi_services 

FEAGI Service Layer

The stable application boundary for FEAGI - defines transport-agnostic service interfaces that can be used by any adapter (REST API, ZMQ, embedded).

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    TRANSPORT ADAPTERS                            │
│  Axum/REST, ZMQ Control, Embedded I2C, etc.                     │
└────────────────────────────┬────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│              SERVICE LAYER (This Crate)                          │
│  • NeuronService      - Neuron CRUD operations                  │
│  • GenomeService      - Genome load/save                        │
│  • ConnectomeService  - Cortical area & brain region management │
│  • AnalyticsService   - Statistics & system health              │
└────────────────────────────┬────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│                   DOMAIN LAYER                                   │
│  feagi-bdu, feagi-evo, feagi-burst-engine, feagi-types          │
└─────────────────────────────────────────────────────────────────┘

Design Principles

1. Transport-Agnostic: Services know nothing about HTTP, ZMQ, or I2C
2. Stable Contracts: Trait interfaces don’t change when backend changes
3. Async by Default: All services are async (can be compiled out for embedded)
4. Error Translation: Backend errors are translated to transport-agnostic ServiceError
5. DTO-Based: All parameters and returns use transport-agnostic DTOs

Usage

For Adapter Implementers

Adapters depend on service traits, not implementations:

use feagi_services::{NeuronService, ServiceResult, CreateNeuronParams};

async fn handle_http_request(
    service: &dyn NeuronService,
    req: HttpRequest
) -> HttpResponse {
    // 1. Parse HTTP request to DTO
    let params = CreateNeuronParams { ... };

    // 2. Call service (transport-agnostic)
    let result = service.create_neuron(params).await?;

    // 3. Convert DTO to HTTP response
    HttpResponse::ok(result)
}

For Backend Implementers

Implementations use domain logic (BDU, NPU, Evo):

use feagi_services::{NeuronService, ServiceResult};
use feagi_brain_development::ConnectomeManager;

struct NeuronServiceImpl {
    connectome: Arc<ConnectomeManager>,
}

#[async_trait]
impl NeuronService for NeuronServiceImpl {
    async fn create_neuron(&self, params: CreateNeuronParams) -> ServiceResult<NeuronInfo> {
        // Delegate to domain logic
        self.connectome.create_neuron(...)?;
        Ok(NeuronInfo { ... })
    }
}

Copyright 2025 Neuraville Inc. Licensed under the Apache License, Version 2.0

Re-exports

pub use traits::AnalyticsService;

pub use traits::ConnectomeService;

pub use traits::GenomeService;

pub use traits::NeuronService;

pub use traits::RuntimeService;

pub use traits::SnapshotCreateOptions;

pub use traits::SnapshotMetadata;

pub use traits::SnapshotService;

pub use types::agent_registry::AgentCapabilities;

pub use types::agent_registry::AgentInfo;

pub use types::agent_registry::AgentRegistry;

pub use types::agent_registry::AgentTransport;

pub use types::agent_registry::AgentType;

pub use types::agent_registry::MotorCapability;

pub use types::agent_registry::SensoryCapability;

pub use types::agent_registry::VisionCapability;

pub use types::agent_registry::VisualizationCapability;

pub use types::registration::AreaStatus;

pub use types::registration::CorticalAreaAvailability;

pub use types::registration::CorticalAreaStatus;

pub use types::registration::RegistrationRequest;

pub use types::registration::RegistrationResponse;

pub use types::registration::TransportConfig;

pub use types::BrainRegionInfo;

pub use types::ConnectivityStats;

pub use types::CorticalAreaInfo;

pub use types::CorticalAreaStats;

pub use types::CreateBrainRegionParams;

pub use types::CreateCorticalAreaParams;

pub use types::CreateNeuronParams;

pub use types::CreateSynapseParams;

pub use types::GenomeInfo;

pub use types::LoadGenomeParams;

pub use types::NeuronInfo;

pub use types::RuntimeStatus;

pub use types::SaveGenomeParams;

pub use types::ServiceError;

pub use types::ServiceResult;

pub use types::SynapseInfo;

pub use types::SystemHealth;

pub use types::UpdateCorticalAreaParams;

pub use impls::AnalyticsServiceImpl;

pub use impls::ConnectomeServiceImpl;

pub use impls::GenomeServiceImpl;

pub use impls::NeuronServiceImpl;

pub use impls::RuntimeServiceImpl;

pub use impls::SnapshotServiceImpl;

Modules

genome

Genome-related service utilities for cortical area updates.

impls

Service implementations.

traits

Service trait definitions.

types

Transport-agnostic types for the service layer.

Constants

VERSION

Version of this crate (for feagi-rust version reporting)

Traits

CorticalAreaExt

Extension trait providing business logic methods for CorticalArea