Skip to main content

Module

apcore::module

Trait Module 

Source 
pub trait Module: Send + Sync {
    // Required methods
    fn input_schema(&self) -> Value;
    fn output_schema(&self) -> Value;
    fn description(&self) -> &str;
    fn execute<'life0, 'life1, 'async_trait>(
        &'life0 self,
        inputs: Value,
        ctx: &'life1 Context<Value>,
    ) -> Pin<Box<dyn Future<Output = Result<Value, ModuleError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided methods
    fn stream(
        &self,
        _inputs: Value,
        _ctx: &Context<Value>,
    ) -> Option<ChunkStream> { ... }
    fn describe(&self) -> Value { ... }
    fn preflight(&self) -> PreflightResult { ... }
    fn on_load(&self) -> Result<(), ModuleError> { ... }
    fn on_unload(&self) { ... }
    fn on_suspend(&self) -> Option<Value> { ... }
    fn on_resume(&self, _state: Value) { ... }
}
Expand description

Core trait that all APCore modules must implement.

Required Methods§

Source

fn input_schema(&self) -> Value

Returns the JSON Schema describing this module’s input.

Source

fn output_schema(&self) -> Value

Returns the JSON Schema describing this module’s output.

Source

fn description(&self) -> &str

Returns a human-readable description of this module.

Source

fn execute<'life0, 'life1, 'async_trait>( &'life0 self, inputs: Value, ctx: &'life1 Context<Value>, ) -> Pin<Box<dyn Future<Output = Result<Value, ModuleError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Execute the module with the given inputs and context.

Provided Methods§

Source

fn stream(&self, _inputs: Value, _ctx: &Context<Value>) -> Option<ChunkStream>

Stream execution — returns an async Stream of output chunks.

Returns None if the module does not support streaming, signaling the executor to fall back to execute(). Modules that support streaming should override this to yield chunks incrementally — each yield is delivered to the caller as soon as it is produced (true streaming, no buffering).

Note: this method is not async even though it returns a stream. The returned ChunkStream is itself an async iterator; constructing it must be cheap and synchronous so the executor can wire it into its own pipeline before the first chunk is awaited.

Validation contract: Executor::stream validates the module’s merged output (all chunks deep-merged) against output_schema only after the stream is exhausted (Phase 3). Individual chunks are not validated as they are yielded. Callers performing incremental chunk processing must tolerate receiving chunks that may not independently satisfy output_schema. If per-chunk schema guarantees are required, validate each chunk inside this method before yielding it.

Source

fn describe(&self) -> Value

Return a structured description of this module for AI/LLM consumption (spec §5.6). Default: builds description from input_schema, output_schema, and description.

Source

fn preflight(&self) -> PreflightResult

Run preflight checks before execution.

Source

fn on_load(&self) -> Result<(), ModuleError>

Called after the module is registered.

Returns Err to signal that the module failed to initialise; the registry rolls back the insertion so no half-initialised module remains registered. Aligns with apcore-python Registry._invoke_on_load.

Default: no-op (Ok(())).

Source

fn on_unload(&self)

Called before the module is unregistered. Default: no-op.

Source

fn on_suspend(&self) -> Option<Value>

Called before hot-reload to capture state. Returns state dict for on_resume(). Default: returns None (no state to preserve).

Source

fn on_resume(&self, _state: Value)

Called after hot-reload to restore state from on_suspend(). Default: no-op.

Implementors§