Contributing to OGuardAI

How to set up the development environment, run tests, follow branch strategy, and submit changes to OGuardAI.

Prerequisites

Setup

# Clone the repository
git clone https://github.com/oronts/oguardai.git
cd oguardai

# Rust -- build all crates
cargo build --workspace

# Python -- install dependencies
cd python/detector-core && uv sync && cd ../..
cd python/sdk-py && uv sync && cd ../..

# TypeScript -- install dependencies
pnpm install

Branch Strategy

Branch Naming

Use the format {type}/guardai-{crate}-{description}:

• feat/oguardai-tokenizer-streaming -- new streaming support in the tokenizer
• fix/oguardai-server-cors-headers -- fix CORS header handling in the server
• docs/oguardai-api-examples -- documentation updates
• refactor/oguardai-session-cleanup -- internal restructuring

Running Tests

Rust

# Run all tests
cargo test --workspace

# Run tests for a specific crate
cargo test -p guardai-core
cargo test -p guardai-tokenizer

# Run with output
cargo test --workspace -- --nocapture

Python

cd python/detector-core
uv run pytest

cd python/sdk-py
uv run pytest

TypeScript

pnpm test

Full Validation

Before submitting a PR, run all checks:

# Rust
cargo fmt --check
cargo clippy -- -D warnings
cargo test --workspace

# Python
ruff check python/
ruff format --check python/
cd python/detector-core && uv run pytest && cd ../..

# TypeScript
pnpm run lint
pnpm run format:check
pnpm test

Pull Request Process

1. Create a feature branch from develop.
2. Write tests first (TDD). Every new feature or bug fix must have tests.
3. Ensure all checks pass -- formatting, linting, and tests for all affected ecosystems (Rust, Python, TypeScript).
4. Open a PR against develop.
5. One approval required from a maintainer.
6. Squash merge to keep the commit history linear.

PR Requirements

• All CI checks pass (formatting, linting, tests, audit).
• No reduction in test coverage for changed files.
• No unwrap() in Rust production code (use ? or expect("reason")).
• No any in TypeScript (use proper types or unknown with narrowing).
• No PII in logs, error messages, or test fixtures (use synthetic data only).
• PR title follows conventional commit format.

Commit Message Format

Use Conventional Commits:

<type>(<scope>): <description>

Examples

feat(tokenizer): add deterministic token ordering by span position
fix(rehydrate): handle missing underscore in token ID repair pass
test(session): add sealed blob expiry and tampering tests
docs(api): add curl examples for streaming endpoints

Use the crate or package name without the guardai- prefix as scope: tokenizer, rehydrate, session, policy, server, cli, sdk-ts, sdk-py, mcp.

Code Style

Rust

• Format with cargo fmt. Lint with cargo clippy -- -D warnings. Zero warnings.
• No unwrap() in library or production code. Use ? with thiserror error types.
• No println! -- use tracing macros for all output.
• No unsafe without a // SAFETY: comment explaining the invariant.
• Pre-compile regex patterns at initialization, never in per-call paths.
• 500 LOC max per file, 50 lines max per function.

TypeScript

• Strict mode: strict: true in tsconfig.json.
• Lint with ESLint, format with Prettier.
• No any. No console.log -- use pino.
• Validate inputs with Zod at every boundary.

Python

• Type hints on all public functions. Every file starts with from __future__ import annotations.
• Lint and format with ruff. Zero warnings.
• No print() -- use structlog.
• Use pydantic or dataclasses for data structures.

License

By contributing to OGuardAI, you agree that your contributions will be licensed under the Apache License 2.0.