Docs /guides/ Contributing Templates
guides / community

Contributing Templates

Set up, design, validate and submit reusable Sinapsis community Templates.

contributingtemplatestestingpythoncommunityDocumentation latest

Source: Sinapsis Contribution Guidelines — GitHub

This guide summarises how to contribute reusable Sinapsis Templates. The canonical contribution policy and complete examples live in sinapsis-contrib/CONTRIBUTING.md; follow that file for current commands and review requirements.

For the starting repository and sample Agents, see Community Templates.

Set up your development environment

The source guide lists Python 3.10+, Git and uv as prerequisites. Clone the project and install development dependencies:

Terminalbash
git clone https://github.com/Sinapsis-AI/sinapsis-contrib.git
cd sinapsis-contrib
uv sync --dev

The repository uses pytest (including asynchronous tests), Ruff, pre-commit and ty for local validation.

Add a Template

Create each implementation under src/<package_name>/templates/ and expose its public class through the package's templates/__init__.py lookup and __all__. Put example Agent configuration under src/<package_name>/configs/.

A normal Template accepts a DataContainer and returns a DataContainer. The source guide asks authors to implement execute() and/or async_execute(), validate configuration through TemplateAttributes, use type hints, and provide meaningful errors. Templates should generally be single-purpose, stateless and deterministic where possible.

Avoid mutating the input container in place. The contributing guide recommends returning a new or combined container when producing outputs, and its baseline contract tests check input immutability. Explicit Agent data-flow operations should be used for branching rather than implementing custom orchestration inside a Template.

Test and document the behaviour

Register new Templates for baseline contract tests, then add tests for their actual business logic: successful results, packet content and metadata, invalid configuration, failure modes, and asynchronous execution when supported.

Terminalbash
uv run pytest
uv run pre-commit run --all-files
uv run ty check

Document supported packet types, configuration fields, external dependencies and an example Agent YAML. The original contributor guide describes Sphinx builds for the Template package repository; this centralised documentation portal has a different Markdown publishing workflow. Continue to run the package's own documentation checks where its CI requires them.

Before opening a pull request

Confirm that the Template is discoverable, behaves correctly with the DataContainer contract, has focused tests, passes quality checks, and includes updated configuration and documentation. Docker support is optional, with sinapsis:base and sinapsis-nvidia:base cited by the repository for CPU/GPU cases respectively.

For the full checklist, authentication requirements for asynchronous packages, versioning and contribution policy, see CONTRIBUTING.md.

Published from Git revision 7b7ba25d627b