Contributing to OGuardAI

How to set up the development environment, run tests, follow branch strategy, and submit changes to the Apache-2.0 surfaces of OGuardAI: sdks/**, packages/**, apps/mcp-server/**, examples/**, and schemas/**.

The runtime (the Rust crates, apps/server, apps/cli, apps/proxy, apps/detector-py, and python/detector-core) is proprietary. Runtime contributions are governed by a contributor licence agreement, documented in CONTRIBUTING.md in the repository.

Prerequisites

Node.js support tracks the upstream release schedule: every LTS line still in maintenance is supported, a line is dropped when it reaches end-of-life, and CI runs on the oldest supported line.

Setup

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

# TypeScript -- install dependencies
pnpm install

# Python SDK -- install dependencies
cd sdks/python && uv sync && cd ../..

The Go SDK (sdks/go) and the Java SDK (sdks/java) build with their own toolchains directly; neither needs a workspace-wide install step.

Branch Strategy

main ───────────────────────────────────────── v0.1.0
  │                                              ↑
  └─ develop ──────────────────────────── merge ─┘
       │              ↑            ↑
       ├─ feat/streaming ──────────┘
       │   (add streaming, tests)
       │                           ↑
       └─ fix/server-cors ─────────┘
           (fix cors)

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

Python SDK

cd sdks/python
uv run pytest

TypeScript

pnpm test

Go SDK

cd sdks/go && go test ./...

Java SDK

cd sdks/java && mvn test

Full Validation

Before submitting a PR, run all checks for the surface you touched:

# Python SDK
ruff check sdks/python/
ruff format --check sdks/python/
cd sdks/python && uv run pytest && cd ../..

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

# Go SDK
cd sdks/go && go vet ./... && go test ./... && cd ../..

# Java SDK
cd sdks/java && mvn verify && cd ../..

# Licence boundary (runtime proprietary, SDKs and documentation under Apache-2.0)
scripts/check-license-boundary.sh

check-license-boundary.sh has three outcomes and fails closed: exit 0 every check ran and was clean, exit 1 a check found a boundary violation, exit 2 a check could not run, so what it guards is unverified. It never reports a pass for a check it could not perform. Run it whenever you add a package, move a path across the boundary, or change a license field.

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 (Python, TypeScript, Go, Java).
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 package name as scope: sdk-ts, sdk-py, sdk-go, sdk-java, mcp.

Code Style

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.

Go

• Format with gofmt. Vet with go vet ./....
• Wrap errors with %w; do not discard them.

Java

• Format and build with the project's Maven configuration (mvn verify).

License

Every commit must be signed off under the Developer Certificate of Origin (DCO) 1.1: add a Signed-off-by trailer with git commit -s. It certifies you wrote the change or have the right to submit it. The full text is at developercertificate.org.

Contributions are accepted under the licence of the component you change: the runtime is proprietary software, the property of Oronts GmbH, and the SDKs, examples, schemas, and documentation are under the Apache License 2.0. Contributions to the runtime paths are additionally governed by a contributor licence agreement with Oronts; that text is prepared with legal counsel and is not yet published, so until it is, external contributions to the runtime paths cannot be accepted. Apache-licensed contributions need only the DCO sign-off.