Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (84 loc) · 3.73 KB

CONTRIBUTING.md

File metadata and controls

115 lines (84 loc) · 3.73 KB
Raw

Contributing To TinyAgents

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 --workspace --all-targets -- -D warnings
cargo build --workspace --all-targets
cargo test --workspace

The bundled example should also run:

cargo run -p tinyagents-integration-tests --example basic_graph

Cargo features are package-local. tinyagents-harness exposes sqlite, tools, multimodal, and tracing; tinyagents-graph exposes sqlite and tracing; tinyagents-registry and tinyagents-session expose tracing. To build with a feature enabled, pass it on the relevant package:

cargo test -p tinyagents-harness --features sqlite
cargo test -p tinyagents-integration-tests --features sqlite

Submodules

This repository has two git submodules, and they are not interchangeable:

  • vendor/tinytools — the vendored tool vocabulary crate Cargo.toml resolves tinytools from (vendor/tinytools/crates/tinytools). This one is required: without it, cargo cannot even read the manifest, and every build fails at "Updating crates.io index" with "failed to read vendor/tinytools/crates/tinytools/Cargo.toml".
  • wiki — the published GitHub wiki, 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 down both:

git clone --recurse-submodules https://github.com/tinyhumansai/tinyagents.git
# or, in an existing checkout:
git submodule update --init --recursive
# or, to fetch only the required build dependency:
git submodule update --init vendor/tinytools

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 a sibling <module>_tests.rs (mod_tests.rs beside a mod.rs). Integration tests belong in tests/.

Pull Request Checklist

Before opening a pull request:

  • run cargo fmt --check
  • run cargo clippy --workspace --all-targets -- -D warnings
  • run cargo build --workspace --all-targets
  • run cargo test --workspace
  • 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 graph runtime 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.