Contribute

This section is for contributors changing the Neat Library itself. It explains how the repository is structured, how to build and test changes, and which contracts must stay stable for application developers.

Contributor Orientation

The Neat Library is the C++/Python library and runtime in this repository. It loads model archives, composes and validates pipelines, runs on Modalix hardware, and exposes the public application API. Palette SDK and DevKit Sync are the surrounding development workflow.

When changing this repository, optimize for framework properties that help both humans and agent-assisted development: explicit APIs, deterministic behavior, structured diagnostics, strict validation, and stable public contracts.

Contributor Principles

• Determinism wins — keep element names, generated pipelines, reports, and tests reproducible.
• Debuggability is first-class — failures should produce structured data, not only strings.
• No silent fallback — do not hide model-input bugs or hardware/runtime failures.
• Validate before run — catch structural, caps, shape, and contract errors before runtime.
• Public APIs stay stable — installed headers under include/* require additive, compatible changes.
• Concurrency must be bounded and observable — teardown must not hang and diagnostics must be thread-safe.

Start Here

Understand the repository, naming rules, and expectations before changing code.

• ArchitectureLearn repository structure, module ownership, runtime flow, and extension points.
• Naming ContractUse canonical product, API, package, and type names consistently.
• Coding StandardFollow C++ style, public API, compatibility, and documentation expectations.

Build & Test

Build the framework, validate changes, and work on Python bindings.

• BuildBuild Neat from source and choose CMake profiles or build toggles.
• Test RequirementsKnow which tests and docs updates are expected for each kind of change.
• Python BindingsBuild, test, and package PyNeat bindings as a contributor.

Contracts & Internals

Use these when changing model archives, plugin contracts, or internal packaging.

• MPK ContractUnderstand model archive ingestion, validation, and security rules.
• Plugin JSON Truth MapReview the frozen SIMA plugin JSON contract map.
• AppComplex PackagingBuild and install the gated appcomplex workspace service package.

Release & Maintenance

Use these for release gates, cleanup plans, and long-lived design guidance.

• Release ChecklistFollow release-blocking conditions, required checks, and reproducible steps.
• Error Taxonomy RolloutTrack structured error-code migration and verification status.
• Agentic WorkflowSee why the API is structured for human and AI-assisted development.