feat(guardrail): add definitions and traits

[bzp2010]

Summary by CodeRabbit

• New Features
  • Added a guardrail system for message-level validation with explicit input and output stage support.
  • Messages can be allowed, rewritten, or blocked with a documented outcome model.
  • Multimodal content supported (text, images) and tool-call information preserved in checks.
  • Introduced an async runtime contract for performing guardrail checks.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cdc2c177-8477-4be5-ae60-ec2a765c7fa5

📥 Commits

Reviewing files that changed from the base of the PR and between 70fb365 and bdec91c.

📒 Files selected for processing (1)

• crates/aisix-guardrail/src/lib.rs

✅ Files skipped from review due to trivial changes (1)

• crates/aisix-guardrail/src/lib.rs

---

📝 Walkthrough

Walkthrough

The PR adds a new crate crates/aisix-guardrail implementing guardrail types, payloads, outcomes, an async runtime trait, unit tests, and integrates the crate into the workspace and root crate dependencies.

Changes

Guardrail Subsystem

Layer / File(s)	Summary
Workspace Integration Cargo.toml	Root workspace members updated to include crates/aisix-guardrail; root [dependencies] adds path dependency on the new crate.
Crate Manifest crates/aisix-guardrail/Cargo.toml	New crate declares package metadata and workspace-managed dependencies (async-trait, serde, utoipa).
Module Export crates/aisix-guardrail/src/lib.rs	Root library exports the public traits module.
Metadata Trait crates/aisix-guardrail/src/traits.rs	GuardrailMeta trait defines guardrail name and supported execution stages with default implementations.
Core Enums crates/aisix-guardrail/src/traits.rs	GuardrailStage (Input, Output) and GuardrailRole (System, User, Assistant, Tool) enums.
Message Content Model crates/aisix-guardrail/src/traits.rs	GuardrailMessageContent and GuardrailContentPart support text and multipart message content (including image URLs).
Tool & Image Structures crates/aisix-guardrail/src/traits.rs	GuardrailImageUrl and GuardrailToolCall model image metadata and tool invocation details.
Message Wrapper crates/aisix-guardrail/src/traits.rs	GuardrailMessage aggregates role, optional content, optional name, optional tool calls, and optional tool_call_id.
Payload & Stage Mapping crates/aisix-guardrail/src/traits.rs	InputGuardrailPayload, OutputGuardrailPayload, and GuardrailCheckPayload unify message batches and provide stage() mapping.
Execution Outcome crates/aisix-guardrail/src/traits.rs	GuardrailOutcome enum represents Allow, Rewrite(with payload), or Block(with reason).
Async Runtime Trait crates/aisix-guardrail/src/traits.rs	GuardrailRuntime<C> extends GuardrailMeta and defines async check returning Result<GuardrailOutcome, Self::Error>.
Unit Tests crates/aisix-guardrail/src/traits.rs	Tests exercise stage support defaults, payload stage mapping, tool-call embedding and representation, multimodal content preservation, and rewrite outcome payload preservation.

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
E2e Test Quality Review	⚠️ Warning	E2E tests are blocking and absent. PR has 6 unit tests for data structures only. Core GuardrailRuntime::check() trait is untested. Error handling paths absent. No implementation testing.	Add E2E tests: (1) Mock GuardrailRuntime implementation, (2) Input/Output payload flow through check(), (3) Error scenarios, (4) Allow/Rewrite/Block outcomes. Test the trait contract, not just data structures.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding guardrail definitions and traits to a new crate module, which is the core focus of all changes in this PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Security Check	✅ Passed	No security issues found. Guardrail framework adds trait definitions and message types with no logging, database storage, authorization logic, TLS config, or unsafe operations.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch bzp/feat-guardrail-fw

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

crates/aisix-guardrail/src/traits.rs (1)

23-107: ⚡ Quick win

Add /// docs for the public API surface.

Several public enums/structs/methods in this section are undocumented, which violates the repo Rust API doc rule.

As per coding guidelines, "Use /// for doc comments on public items in Rust".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/aisix-guardrail/src/traits.rs` around lines 23 - 107, The public API
items in this file lack Rust doc comments; add concise /// documentation to each
public enum/struct/trait and their public methods to satisfy the crate's doc
rule—specifically annotate GuardrailRole, GuardrailMessageContent,
GuardrailContentPart, GuardrailImageUrl, GuardrailToolCall, GuardrailMessage,
InputGuardrailPayload, OutputGuardrailPayload, GuardrailCheckPayload (and its
stage method), GuardrailOutcome, and the GuardrailRuntime trait (including the
associated type Error and the check method) with short descriptions of their
purpose, fields/variants, and expected behavior/semantics so external users can
read API docs.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/aisix-guardrail/src/lib.rs`:
- Line 1: The crate declares `pub mod guardrails;` but the module file is
missing; create a module file named either `guardrails.rs` or a
`guardrails/mod.rs` containing the guardrails module (at minimum a small public
stub such as `pub fn init() {}` or desired public types/funcs) so the compiler
can find and load the `guardrails` module referenced by `pub mod guardrails;`.

---

Nitpick comments:
In `@crates/aisix-guardrail/src/traits.rs`:
- Around line 23-107: The public API items in this file lack Rust doc comments;
add concise /// documentation to each public enum/struct/trait and their public
methods to satisfy the crate's doc rule—specifically annotate GuardrailRole,
GuardrailMessageContent, GuardrailContentPart, GuardrailImageUrl,
GuardrailToolCall, GuardrailMessage, InputGuardrailPayload,
OutputGuardrailPayload, GuardrailCheckPayload (and its stage method),
GuardrailOutcome, and the GuardrailRuntime trait (including the associated type
Error and the check method) with short descriptions of their purpose,
fields/variants, and expected behavior/semantics so external users can read API
docs.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bf5fa928-472b-436c-a223-0f0fc38409ca

📥 Commits

Reviewing files that changed from the base of the PR and between fce3c6f and 70fb365.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (4)

• Cargo.toml
• crates/aisix-guardrail/Cargo.toml
• crates/aisix-guardrail/src/lib.rs
• crates/aisix-guardrail/src/traits.rs