Model Class

Loaded form of a compiled model archive; the simplified entry point to run inference on Modalix. More...

Declaration

class simaai::neat::Model { ... }

Included Headers

#include <Model.h>

Enumerations Index

enum class	Stage { ... }
	Selector for fragment(Stage) and backend_fragment(Stage). More...

Friends Index

struct	internal::ModelAccess

Public Constructors Index

	Model (const std::string &model_path)
	Load and validate a compiled model archive at the given path with default options. More...
	Model (const std::string &model_path, const Options &opt)
	Load and validate a compiled model archive with explicit options. More...
	Model (Model &&) noexcept
	Move-constructible. More...

Public Destructor Index

	~Model ()
	Destructor; releases the impl and (optionally) cleans up extracted model-archive data. More...

Public Operators Index

Model &	operator= (Model &&) noexcept
	Move-assignable. (Models are not copyable.). More...

Public Member Functions Index

simaai::neat::Graph	preprocess () const
	Returns the preprocess portion of the model's pipeline as a Graph. More...
simaai::neat::Graph	inference () const
	Returns the MLA inference portion of the model's pipeline as a Graph. More...
simaai::neat::Graph	postprocess () const
	Returns the postprocess portion of the model's pipeline as a Graph. More...
simaai::neat::Graph	graph () const
	Returns the model's full route as a public Graph fragment. More...
simaai::neat::Graph	graph (RouteOptions opt) const
	Returns the model's full route as a public Graph, optionally with explicit Input/Output boundary Nodes when requested by RouteOptions. More...
std::vector< TensorSpec >	input_specs () const
	Returns one spec per ingress port. More...
std::vector< TensorSpec >	output_specs () const
	Returns the produced output tensor specs (multiple for multi-head models). More...
int	compiled_batch_size () const
	Returns the batch size the model was compiled with. More...
ResolvedPreprocessPlan	resolved_preprocess_plan () const
	Returns the full resolved preprocess plan (intent-driven; richer than preprocess_requirements()). More...
PreprocessRequirements	preprocess_requirements () const
	Returns concrete preprocess parameters (resize, color, quant, tess) the model needs. More...
ModelInfo	info () const
	Returns the full diagnostic snapshot of the loaded model and its route. More...
std::unordered_map< std::string, std::string >	metadata () const
	Returns free-form key/value metadata declared by the model author in the manifest. More...
Graph	fragment (Stage stage) const
	Returns one specific stage of the pipeline as a Graph. More...
std::string	backend_fragment (Stage stage) const
	Returns the GStreamer launch fragment for one specific stage (debugging / Graph::custom() use). More...
simaai::neat::InputOptions	input_appsrc_options (bool tensor_mode) const
	Returns the appsrc input options the planner derived for a given input mode (tensor or media). More...
std::vector< simaai::neat::InputOptions >	input_appsrc_options_list (bool tensor_mode) const
	Per-input variant of input_appsrc_options for multi-input models. More...
std::string	find_config_path_by_plugin (const std::string &plugin_id) const
	Find the path to a per-stage config file in the extracted model archive by plugin ID. More...
std::string	find_config_path_by_processor (const std::string &processor) const
	Find the path to a per-stage config file in the extracted model archive by processor name (CVU/MLA/APU). More...
std::string	infer_output_name () const
	Returns the canonical output element name for the inference stage (used in pipeline string emission). More...
Runner	build ()
	Build a long-lived Runner from this Model with default options. More...
Runner	build (const RouteOptions &opt)
	Build a Runner with explicit route options. More...
Runner	build (const simaai::neat::RunOptions &run_opt)
	Build a Runner with explicit runtime options. More...
Runner	build (const RouteOptions &opt, const simaai::neat::RunOptions &run_opt)
	Build a Runner with explicit route and runtime options. More...
Runner	build (const simaai::neat::TensorList &inputs, const RouteOptions &opt=default_route_options(), const simaai::neat::RunOptions &run_opt=default_run_options())
	Build a Runner and seed the build with sample input(s). More...
Runner	build (const simaai::neat::Sample &inputs, const RouteOptions &opt=default_route_options(), const simaai::neat::RunOptions &run_opt=default_run_options())
	Build variant that seeds with full Sample inputs (carrying per-buffer metadata). More...
simaai::neat::ExecutionPlan	execution_plan ()
	Describe what the matching build(...) executes. More...
simaai::neat::ExecutionPlan	execution_plan (const RouteOptions &opt)
	Execution plan of build(opt). More...
simaai::neat::ExecutionPlan	execution_plan (const simaai::neat::RunOptions &run_opt)
	Execution plan of build(run_opt). More...
simaai::neat::ExecutionPlan	execution_plan (const RouteOptions &opt, const simaai::neat::RunOptions &run_opt)
	Execution plan of build(opt, run_opt). More...
simaai::neat::ExecutionPlan	execution_plan (const simaai::neat::TensorList &inputs, const RouteOptions &opt=default_route_options(), const simaai::neat::RunOptions &run_opt=default_run_options())
	Execution plan of build(inputs, opt, run_opt) for Tensor inputs. More...
simaai::neat::ExecutionPlan	execution_plan (const simaai::neat::Sample &inputs, const RouteOptions &opt=default_route_options(), const simaai::neat::RunOptions &run_opt=default_run_options())
	Execution plan of build(inputs, opt, run_opt) for Sample inputs. More...
simaai::neat::TensorList	run (const simaai::neat::TensorList &inputs, int timeout_ms=-1)
	One-shot-style inference for the simplest applications. More...
simaai::neat::Sample	run (const simaai::neat::Sample &inputs, int timeout_ms=-1)
	One-shot inference with full Sample inputs. More...
BenchmarkReport	benchmark (const BenchmarkOptions &options)
	Run a small benchmark for simple model execution. More...
BenchmarkReport	benchmark (int num_samples=100)
BenchmarkReport	benchmark (int num_samples, bool include_plugin_latency)
	Deprecated: use benchmark(num_samples). True also collects plugin latency. More...
BenchmarkReport	benchmark (bool include_plugin_latency)
	Deprecated: use benchmark(). True also collects plugin latency. More...

Private Member Functions Index

Runner	build_with_model_options (const simaai::neat::TensorList &inputs, const Model::RouteOptions &opt, const simaai::neat::RunOptions &run_opt, const Model::Options &model_opt)

Private Member Attributes Index

std::unique_ptr< Impl >	impl_

Private Static Functions Index

static const RouteOptions &	default_route_options ()
static const simaai::neat::RunOptions &	default_run_options ()

Description

Loaded form of a compiled model archive; the simplified entry point to run inference on Modalix.

A Model owns an extracted model archive, the parsed inference contract, and the route plan derived from it. Once constructed it exposes:

• Graph fragments — preprocess(), inference(), postprocess(), graph() — for composing into a user-built Graph.
• run(input) convenience methods that lazily build one internal runner on first use, then reuse it for subsequent calls. The shortest path from "I have a tensor" to "here are detections."
• build(...) that returns a long-lived Runner for streaming use cases (push many inputs over time, pull results asynchronously).
• Introspection (input_specs(), output_specs(), info(), metadata()) so application code can ask the Model what shape/dtype/topology it expects and produces.

 namespace neat = simaai::neat;

 neat::Model model("/models/yolov8.tar.gz");

 neat::TensorList result =

  model.run(neat::TensorList{input_tensor}, 2000); // timeout_ms; shortest path

For applications that need more control (custom pre/post nodes, multiple cameras, RTSP server output), graduate from Model::run() to composing a Graph that includes model.graph() plus your own input/output nodes.

See Also

Graph

See Also

"Model is a Graph in disguise" (§0.12 of the design deep dive)

Definition at line 226 of file Model.h.

Enumerations

Stage

enum class simaai::neat::Model::Stage

strong

Selector for fragment(Stage) and backend_fragment(Stage).

Enumeration values

Preprocess	Pre-MLA portion only (resize, color-convert, normalize, quant, tess)
Inference	MLA inference stage only
Postprocess	Post-MLA portion only (detess, dequant, cast, BoxDecode if applicable)
Full	Full pipeline: Preprocess + Inference + Postprocess

Lets advanced users grab one specific portion of the model's pipeline.

Definition at line 502 of file Model.h.

Friends

internal::ModelAccess

friend struct internal::ModelAccess

Definition at line 807 of file Model.h.

Public Constructors

Model()

simaai::neat::Model::Model (const std::string & model_path)

explicit

Load and validate a compiled model archive at the given path with default options.

Equivalent to Model(model_path, Options{}). The constructor extracts the .tar.gz, validates the manifest (rejecting malformed or malicious archives), and runs the route planner. Throws NeatError on any failure (with a structured GraphReport).

Parameters

model_path

Filesystem path to a .tar.gz model archive.

Exceptions

<a href="/reference/cppapi/classes/simaai-neat-neaterror">NeatError</a>

on archive validation failure, manifest parse error, or unsupported route.

Definition at line 519 of file Model.h.

Model()

simaai::neat::Model::Model (const std::string & model_path, const Options & opt)

explicit

Load and validate a compiled model archive with explicit options.

Parameters

model_path	Filesystem path to a .tar.gz model archive.
opt	Options controlling preprocess, postprocess decode, naming, lifecycle, and verbosity.

Exceptions

<a href="/reference/cppapi/classes/simaai-neat-neaterror">NeatError</a>

on archive validation failure, manifest parse error, or unsupported route.

Definition at line 528 of file Model.h.

Model()

simaai::neat::Model::Model (Model &&)

noexcept

Move-constructible.

Definition at line 530 of file Model.h.

Public Destructor

~Model()

simaai::neat::Model::~Model ()

Destructor; releases the impl and (optionally) cleans up extracted model-archive data.

Definition at line 532 of file Model.h.

Public Operators

operator=()

Model & simaai::neat::Model::operator= (Model &&)

noexcept

Move-assignable. (Models are not copyable.).

Definition at line 531 of file Model.h.

Public Member Functions

backend_fragment()

std::string simaai::neat::Model::backend_fragment (Stage stage)

Returns the GStreamer launch fragment for one specific stage (debugging / Graph::custom() use).

Definition at line 578 of file Model.h.

benchmark()

BenchmarkReport simaai::neat::Model::benchmark (const BenchmarkOptions & options)

Run a small benchmark for simple model execution.

Uses BenchmarkOptions::inputs, or generates deterministic synthetic input tensors from input_specs() when none are given, runs a fixed warmup, measures single-flight latency and async logical-inference throughput separately, records board telemetry through Sentinel during the throughput pass, prints a compact summary, and returns headline metrics. Each pass lasts at least BenchmarkOptions::min_duration_ms (10 s by default).

Definition at line 792 of file Model.h.

benchmark()

BenchmarkReport simaai::neat::Model::benchmark (int num_samples=100)

Definition at line 793 of file Model.h.

benchmark()

BenchmarkReport simaai::neat::Model::benchmark (int num_samples, bool include_plugin_latency)

Deprecated: use benchmark(num_samples). True also collects plugin latency.

Definition at line 796 of file Model.h.

benchmark()

BenchmarkReport simaai::neat::Model::benchmark (bool include_plugin_latency)

Deprecated: use benchmark(). True also collects plugin latency.

Definition at line 799 of file Model.h.

build()

Runner simaai::neat::Model::build ()

Build a long-lived Runner from this Model with default options.

Use this for streaming workloads (push many inputs over time, pull asynchronously). For one-shot inference, prefer run().

Returns

A Runner ready for push/pull.

Exceptions

<a href="/reference/cppapi/classes/simaai-neat-neaterror">NeatError</a>

on validation or build failure (with structured GraphReport).

Definition at line 693 of file Model.h.

build()

Runner simaai::neat::Model::build (const RouteOptions & opt)

Build a Runner with explicit route options.

Definition at line 695 of file Model.h.

build()

Runner simaai::neat::Model::build (const simaai::neat::RunOptions & run_opt)

Build a Runner with explicit runtime options.

Definition at line 697 of file Model.h.

build()

Runner simaai::neat::Model::build (const RouteOptions & opt, const simaai::neat::RunOptions & run_opt)

Build a Runner with explicit route and runtime options.

Definition at line 699 of file Model.h.

build()

Runner simaai::neat::Model::build (const simaai::neat::TensorList & inputs, const RouteOptions & opt=default_route_options(), const simaai::neat::RunOptions & run_opt=default_run_options())

Build a Runner and seed the build with sample input(s).

Seeding the build with an input lets the planner perform build-time adaptation: tightening caps to match the actual input shape, picking concrete pixel formats, validating that the input is compatible. The BuildAdaptationSummary in the resulting GraphReport records what adaptations were applied.

Parameters

inputs	One Tensor per ingress port. For single-input models pass a single-element list.
opt	Graph options (defaults are sensible).
run_opt	Runtime options (queue depth, overflow policy, async/sync mode).

Definition at line 713 of file Model.h.

build()

Runner simaai::neat::Model::build (const simaai::neat::Sample & inputs, const RouteOptions & opt=default_route_options(), const simaai::neat::RunOptions & run_opt=default_run_options())

Build variant that seeds with full Sample inputs (carrying per-buffer metadata).

Definition at line 717 of file Model.h.

compiled_batch_size()

int simaai::neat::Model::compiled_batch_size ()

Returns the batch size the model was compiled with.

Defaults to 1 when the model is not batched. Callers that drive multiple logical inferences per push/pull cycle should use this to size their input batches. Tensor input_specs() already include any MPK-authored batch axis, including batch one.

Definition at line 562 of file Model.h.

execution_plan()

simaai::neat::ExecutionPlan simaai::neat::Model::execution_plan ()

Describe what the matching build(...) executes.

Builds the Model with the same arguments and startup preflight off, reads the plan that build recorded, and closes the pipeline. The plan lists the Model's nodes (preprocessing, quantization, EV74/A65 kernels, MLA), where each one runs, and the tensors between them.

Exceptions

<a href="/reference/cppapi/classes/simaai-neat-neaterror">NeatError</a>

on the errors build(...) raises.

Definition at line 735 of file Model.h.

execution_plan()

simaai::neat::ExecutionPlan simaai::neat::Model::execution_plan (const RouteOptions & opt)

Execution plan of build(opt).

Definition at line 737 of file Model.h.

execution_plan()

simaai::neat::ExecutionPlan simaai::neat::Model::execution_plan (const simaai::neat::RunOptions & run_opt)

Execution plan of build(run_opt).

Definition at line 739 of file Model.h.

execution_plan()

simaai::neat::ExecutionPlan simaai::neat::Model::execution_plan (const RouteOptions & opt, const simaai::neat::RunOptions & run_opt)

Execution plan of build(opt, run_opt).

Definition at line 741 of file Model.h.

execution_plan()

simaai::neat::ExecutionPlan simaai::neat::Model::execution_plan (const simaai::neat::TensorList & inputs, const RouteOptions & opt=default_route_options(), const simaai::neat::RunOptions & run_opt=default_run_options())

Execution plan of build(inputs, opt, run_opt) for Tensor inputs.

Definition at line 745 of file Model.h.

execution_plan()

simaai::neat::ExecutionPlan simaai::neat::Model::execution_plan (const simaai::neat::Sample & inputs, const RouteOptions & opt=default_route_options(), const simaai::neat::RunOptions & run_opt=default_run_options())

Execution plan of build(inputs, opt, run_opt) for Sample inputs.

Definition at line 750 of file Model.h.

find_config_path_by_plugin()

std::string simaai::neat::Model::find_config_path_by_plugin (const std::string & plugin_id)

Find the path to a per-stage config file in the extracted model archive by plugin ID.

Definition at line 585 of file Model.h.

find_config_path_by_processor()

std::string simaai::neat::Model::find_config_path_by_processor (const std::string & processor)

Find the path to a per-stage config file in the extracted model archive by processor name (CVU/MLA/APU).

Definition at line 588 of file Model.h.

fragment()

Graph simaai::neat::Model::fragment (Stage stage)

Returns one specific stage of the pipeline as a Graph.

Definition at line 575 of file Model.h.

graph()

simaai::neat::Graph simaai::neat::Model::graph ()

Returns the model's full route as a public Graph fragment.

Definition at line 543 of file Model.h.

graph()

simaai::neat::Graph simaai::neat::Model::graph (RouteOptions opt)

Returns the model's full route as a public Graph, optionally with explicit Input/Output boundary Nodes when requested by RouteOptions.

Definition at line 546 of file Model.h.

infer_output_name()

std::string simaai::neat::Model::infer_output_name ()

Returns the canonical output element name for the inference stage (used in pipeline string emission).

Definition at line 591 of file Model.h.

inference()

simaai::neat::Graph simaai::neat::Model::inference ()

Returns the MLA inference portion of the model's pipeline as a Graph.

Definition at line 539 of file Model.h.

info()

ModelInfo simaai::neat::Model::info ()

Returns the full diagnostic snapshot of the loaded model and its route.

Definition at line 569 of file Model.h.

input_appsrc_options()

simaai::neat::InputOptions simaai::neat::Model::input_appsrc_options (bool tensor_mode)

Returns the appsrc input options the planner derived for a given input mode (tensor or media).

Definition at line 581 of file Model.h.

input_appsrc_options_list()

std::vector< simaai::neat::InputOptions > simaai::neat::Model::input_appsrc_options_list (bool tensor_mode)

Per-input variant of input_appsrc_options for multi-input models.

Definition at line 583 of file Model.h.

input_specs()

std::vector< TensorSpec > simaai::neat::Model::input_specs ()

Returns one spec per ingress port.

Tensor shapes retain the MPK-authored rank, including a singleton batch axis; batch-one HWC shorthand remains accepted. Image preprocessing inputs describe the dynamic image contract instead.

Definition at line 552 of file Model.h.

metadata()

std::unordered_map< std::string, std::string > simaai::neat::Model::metadata ()

Returns free-form key/value metadata declared by the model author in the manifest.

Definition at line 571 of file Model.h.

output_specs()

std::vector< TensorSpec > simaai::neat::Model::output_specs ()

Returns the produced output tensor specs (multiple for multi-head models).

Definition at line 554 of file Model.h.

postprocess()

simaai::neat::Graph simaai::neat::Model::postprocess ()

Returns the postprocess portion of the model's pipeline as a Graph.

Definition at line 541 of file Model.h.

preprocess()

simaai::neat::Graph simaai::neat::Model::preprocess ()

Returns the preprocess portion of the model's pipeline as a Graph.

Definition at line 537 of file Model.h.

preprocess_requirements()

PreprocessRequirements simaai::neat::Model::preprocess_requirements ()

Returns concrete preprocess parameters (resize, color, quant, tess) the model needs.

Definition at line 567 of file Model.h.

resolved_preprocess_plan()

ResolvedPreprocessPlan simaai::neat::Model::resolved_preprocess_plan ()

Returns the full resolved preprocess plan (intent-driven; richer than preprocess_requirements()).

Definition at line 565 of file Model.h.

run()

simaai::neat::TensorList simaai::neat::Model::run (const simaai::neat::TensorList & inputs, int timeout_ms=-1)

One-shot-style inference for the simplest applications.

The first call lazily builds and caches an internal Runner; later calls reuse that Runner and only push/pull. Use this for unit tests, single-image inference, batch processing, or Python frame loops where rebuilding every frame would be expensive.

Parameters

inputs	Input tensors (one per ingress port).
timeout_ms	Maximum wait for the result, in milliseconds; -1 waits forever.

Returns

The output tensor list.

Exceptions

<a href="/reference/cppapi/classes/simaai-neat-neaterror">NeatError</a>

on build failure or pull timeout/error.

Definition at line 774 of file Model.h.

run()

simaai::neat::Sample simaai::neat::Model::run (const simaai::neat::Sample & inputs, int timeout_ms=-1)

One-shot inference with full Sample inputs.

Definition at line 776 of file Model.h.

Private Member Functions

build_with_model_options()

Runner simaai::neat::Model::build_with_model_options (const simaai::neat::TensorList & inputs, const Model::RouteOptions & opt, const simaai::neat::RunOptions & run_opt, const Model::Options & model_opt)

Definition at line 802 of file Model.h.

Private Member Attributes

impl_

std::unique_ptr<Impl> simaai::neat::Model::impl_

Definition at line 809 of file Model.h.

Private Static Functions

default_route_options()

const RouteOptions & simaai::neat::Model::default_route_options ()

static

Definition at line 680 of file Model.h.

default_run_options()

const simaai::neat::RunOptions & simaai::neat::Model::default_run_options ()

static

Definition at line 681 of file Model.h.

---

The documentation for this class was generated from the following file:

• Model.h

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.