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 the expected input tensor specs (one per ingress port for multi-input models). 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::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 synthetic benchmark for simple model execution. More...
BenchmarkReport	benchmark (int num_samples=100, bool include_plugin_latency=false)
BenchmarkReport	benchmark (bool include_plugin_latency)

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 119 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 392 of file Model.h.

Friends

internal::ModelAccess

friend struct internal::ModelAccess

Definition at line 652 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 409 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 418 of file Model.h.

Model()

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

noexcept

Move-constructible.

Definition at line 420 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 422 of file Model.h.

Public Operators

operator=()

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

noexcept

Move-assignable. (Models are not copyable.)

Definition at line 421 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 466 of file Model.h.

benchmark()

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

Run a small synthetic benchmark for simple model execution.

Generates deterministic synthetic input tensors from input_specs(), runs a fixed warmup, measures single-flight latency and async logical-inference throughput separately, prints a compact summary, and returns headline metrics.

Definition at line 642 of file Model.h.

benchmark()

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

Definition at line 643 of file Model.h.

benchmark()

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

Definition at line 644 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 580 of file Model.h.

build()

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

Build a Runner with explicit route options.

Definition at line 582 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 584 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 586 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 600 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 604 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. The same value is prepended to input_specs()[i].shape when batch > 1.

Definition at line 450 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 473 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 476 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 463 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 433 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 436 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 479 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 429 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 457 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 469 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 471 of file Model.h.

input_specs()

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

Returns the expected input tensor specs (one per ingress port for multi-input models).

Definition at line 440 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 459 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 442 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 431 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 427 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 455 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 453 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 627 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 629 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 647 of file Model.h.

Private Member Attributes

impl_

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

Definition at line 654 of file Model.h.

Private Static Functions

default_route_options()

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

static

Definition at line 567 of file Model.h.

default_run_options()

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

static

Definition at line 568 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.9.8.