0xplaygrounds/.claude/skills/rig-vector-store

<!-- This file is generated by scripts/sync_agent_instruction_files.sh. --> <!-- Do not edit this file directly; update AGENTS.md and re-run the sync script. -->

---

name: rig-vector-store description: > Implement a Rig vector store companion crate. Use when adding a new vector database backend (MongoDB, LanceDB, Qdrant, etc.) or reviewing an existing vector store integration. argument-hint: "[store-backend]" allowed-tools:

• Read
• Glob
• Grep
• Edit
• Write
• Bash

---

Rig Vector Store Implementation

Implement or audit a Rig vector store companion crate.

Requirements:

1. Implement VectorStoreIndex trait with both top_n and top_n_ids.
2. Define an appropriate Filter type for your backend.
3. Use WasmCompatSend / WasmCompatSync bounds.
4. Return proper VectorStoreError variants.
5. Create the store as a separate companion crate (e.g., rig-mongodb).

rig-vector-store-implementation

Vector stores live in separate companion crates (e.g., rig-mongodb, rig-lancedb).

Core Trait

pub trait VectorStoreIndex: WasmCompatSend + WasmCompatSync {
    type Filter: SearchFilter + WasmCompatSend + WasmCompatSync;

    fn top_n<T: for<'a> Deserialize<'a> + WasmCompatSend>(
        &self,
        req: VectorSearchRequest<Self::Filter>,
    ) -> impl Future<Output = Result<Vec<(f64, String, T)>, VectorStoreError>> + WasmCompatSend;

    fn top_n_ids(
        &self,
        req: VectorSearchRequest<Self::Filter>,
    ) -> impl Future<Output = Result<Vec<(f64, String)>, VectorStoreError>> + WasmCompatSend;
}

Requirements

• Implement both top_n and top_n_ids
• Define an appropriate Filter type for your backend
• Use WasmCompatSend/WasmCompatSync bounds (see below)
• Return proper VectorStoreError variants

rig-wasm-compat

Rig supports WebAssembly targets. Since WASM is single-threaded, Send/Sync bounds are unnecessary and can prevent compilation.

The Pattern

#[cfg(not(target_family = "wasm"))]
pub trait WasmCompatSend: Send {}  // native

#[cfg(target_family = "wasm")]
pub trait WasmCompatSend {}        // wasm

#[cfg(not(target_family = "wasm"))]
pub trait WasmCompatSync: Sync {}  // native

#[cfg(target_family = "wasm")]
pub trait WasmCompatSync {}        // wasm

Usage Rules

Always use WasmCompatSend and WasmCompatSync instead of raw Send and Sync in trait bounds.

// Correct
pub trait MyTrait: WasmCompatSend + WasmCompatSync {
    fn do_thing(&self) -> impl Future<Output = ()> + WasmCompatSend;
}

// Incorrect - will break WASM builds
pub trait MyTrait: Send + Sync {
    fn do_thing(&self) -> impl Future<Output = ()> + Send;
}

Boxed Futures

Use WasmBoxedFuture for boxed futures:

pub type WasmBoxedFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;  // native
pub type WasmBoxedFuture<'a, T> = Pin<Box<dyn Future<Output = T> + 'a>>;         // wasm

Conditional Error Types

Some error types need platform-specific bounds:

#[derive(Debug, thiserror::Error)]
pub enum MyError {
    #[cfg(not(target_family = "wasm"))]
    #[error("Error: {0}")]
    Inner(#[from] Box<dyn std::error::Error + Send + Sync + 'static>),

    #[cfg(target_family = "wasm")]
    #[error("Error: {0}")]
    Inner(#[from] Box<dyn std::error::Error + 'static>),
}

rig-quality-gates

Trait Bounds

Use full where clause syntax for readability:

// Correct
impl<T> CompletionModel for MyModel<T>
where
    T: HttpClientExt + Clone + WasmCompatSend + Debug + Default + 'static,
{
    // ...
}

// Avoid inline bounds for complex signatures
impl<T: HttpClientExt + Clone + WasmCompatSend + Debug + Default + 'static> CompletionModel for MyModel<T> {
    // ...
}

Error Handling

DO NOT use String as an error type. Define proper error enums:

// Correct
#[derive(Debug, thiserror::Error)]
pub enum MyError {
    #[error("Failed to parse response: {0}")]
    ParseError(#[from] serde_json::Error),

    #[error("Provider returned error: {0}")]
    ProviderError(String),
}

// Absolutely forbidden
fn do_thing() -> Result<(), String>  // NO

DO NOT stub out error handling:

// Forbidden
let result = fallible_operation().unwrap();  // NO
let result = fallible_operation().expect("this should work");  // NO unless truly impossible

// Correct
let result = fallible_operation()?;
let result = fallible_operation().map_err(MyError::from)?;

Comments

Comments explain WHY, not WHAT.

If you need to explain what code is doing, the code itself is unclear. Rename variables, extract functions, or restructure.

// Bad - explains what
// Increment counter by one
counter += 1;

// Bad - explains what
// Check if user is admin
if user.role == Role::Admin {

// Good - explains why
// Rate limiting resets at midnight UTC, so we need the day boundary
let boundary = timestamp.truncate_to_day();

// Good - explains non-obvious business logic
// Providers may return tool calls split across multiple chunks,
// so we accumulate them by index until the stream ends

Documentation

• Add doc comments (///) to all public items
• Add module-level documentation (//!) to modules
• Include usage examples in doc comments where helpful

TODO Items

TODO items are not allowed in submitted code.

If you need a TODO, the implementation is incomplete. Either:

1. Complete the implementation
2. Don't submit it yet
3. Create a separate issue tracking the future work

// Forbidden
fn process() {
    // TODO: handle edge case
}

// Forbidden
fn process() {
    unimplemented!("will add later")
}

---

Before Submitting

Required Checks

Run these commands and fix all issues before submitting:

cargo fmt
cargo clippy --all-targets --all-features
cargo test

If you cannot run these commands (e.g., environment limitations), explicitly ask the user to run them before the PR is submitted.

Architectural Changes

If your change involves:

• New traits or significant trait modifications
• Changes to the client/provider architecture
• New abstractions or patterns
• Breaking changes to public APIs

Discuss with the user first. Do not implement major architectural changes without explicit approval. Open an issue for discussion if needed.

Self-Review Checklist

Before considering code complete:

• [ ] All error cases handled properly (no .unwrap() or .expect() on fallible operations unless truly impossible)
• [ ] No String error types
• [ ] No TODO comments
• [ ] No stubbed implementations
• [ ] Comments explain "why", not "what"
• [ ] Uses WasmCompatSend/WasmCompatSync instead of Send/Sync
• [ ] Follows existing code patterns in the codebase
• [ ] Includes tests or examples that compile
• [ ] cargo fmt passes
• [ ] cargo clippy --all-targets --all-features passes
• [ ] cargo test passes

---

Commits

DO NOT MAKE COMMITS UNLESS THE USER HAS ASKED YOU TO DO SO. Users should be able to manually verify that what you have done has worked before proceeding with a commit, and may also want to write their own commit messages.

If the PR contains breaking changes, the PR message must list the public API items that have broken and the migration path for each.

What Will Be Rejected

PRs will be rejected if they contain:

• Lazy workarounds - String error types, .unwrap() everywhere, incomplete handling
• TODO items - Submit complete work or don't submit
• Stubbed error handling - Every error path must be properly handled
• Provider API divergence - Don't add fields/features that don't exist in real provider APIs
• Missing WASM compatibility - Using Send/Sync instead of WasmCompat* variants
• Unclear code requiring explanatory comments - Refactor instead
• Architectural changes without discussion - Major changes need approval first

Remember: The quality bar exists because Rig is used in production by many projects. Every contribution must maintain that standard.