Contributing To TinyAgents

July 4, 2026 ยท View on GitHub

Thanks for helping build TinyAgents. This project is early, so the best contributions are small, explicit, tested, and easy to review.

Development Setup

Install a stable Rust toolchain with Rust 2024 support, then run:

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo build --all-targets
cargo test

The bundled example should also run:

cargo run --example basic_graph

To build with the optional embedded SQLite checkpointer or the .ragsh Rhai session runtime, enable the relevant feature:

cargo test --features sqlite
cargo test --features repl

Wiki Submodule

The published GitHub wiki lives in wiki/, checked out as a git submodule pointing at the tinyhumansai/tinyagents.wiki repository. It is not part of the crate build and is not covered by this project's Markdown line-length or review rules. Clone with submodules to pull it down:

git clone --recurse-submodules https://github.com/tinyhumansai/tinyagents.git
# or, in an existing checkout:
git submodule update --init wiki

Do not edit wiki/ content as part of an unrelated code or docs change; wiki edits should be their own commit (or made directly on the wiki) so the submodule pointer update stays easy to review in isolation.

Project Philosophy

TinyAgents should make agent systems explicit and inspectable. Prefer:

  • small modules with narrow responsibilities
  • typed state and typed errors
  • deterministic graph transitions around nondeterministic model calls
  • public APIs that are easy to test
  • declarative workflow definitions that compile through registries and policy
  • examples that show concrete agent behavior rather than abstract promises

New module directories should keep shared type definitions in types.rs and module-local unit tests in test.rs. Integration tests belong in tests/.

Pull Request Checklist

Before opening a pull request:

  • run cargo fmt --check
  • run cargo clippy --all-targets -- -D warnings
  • run cargo build --all-targets
  • run cargo test
  • add or update tests for behavior changes
  • update docs when public APIs, architecture, or examples change
  • keep the PR focused on one logical change

Commit Style

Use concise imperative commit subjects, for example:

Add graph route validation tests
Document expressive language safety boundary

Avoid mixing formatting, refactors, and behavior changes unless they are inseparable.

Issue Triage

Good issues include:

  • the TinyAgents version or commit
  • the relevant module or API
  • a minimal code example when behavior is surprising
  • expected behavior
  • actual behavior
  • commands run locally

Feature requests should explain the agent workflow they unlock, the public API shape they imply, and any safety or observability concerns.

Security

Do not report vulnerabilities through public issues. Use the process in SECURITY.md.