Expose providerMetadata to usageHandler in RAG component

[devin-ai-integration]

Summary

Adds usageHandler support to the RAG component, allowing users to access providerMetadata from embedding operations. This addresses issue #60 where the RAG component did not expose providerMetadata to the usageHandler, unlike the Agent component.

Changes include:

• New UsageHandler type export that receives usage, providerMetadata, model, and provider
• Optional usageHandler in RAG constructor options
• createChunkArgsBatch now captures and returns providerMetadata from embedMany() calls
• usageHandler is called in add() method at all exit points (ready, replaced, normal completion)
• usageHandler is called in search() method when embeddings are generated (requires mutation context)

Review & Testing Checklist for Human

• Context type change in search(): The method signature changed from CtxWith<"runAction"> to CtxWith<"runAction"> & Partial<CtxWith<"runMutation">>. Verify this is acceptable and won't break existing callers.
• usageHandler in search() only fires with mutation context: The usageHandler is only called if ctx.runMutation exists. Confirm this behavior is expected (users calling search from action-only context won't get usage callbacks).
• providerMetadata merging: When processing multiple batches, providerMetadata is merged via spread operator. Verify this doesn't cause issues if providers return conflicting keys.
• Test end-to-end: Configure a RAG instance with a usageHandler and verify providerMetadata (e.g., gateway.cost for OpenAI) is correctly passed through during add() and search() operations.

Notes

Fixes #60

Link to Devin run: https://app.devin.ai/sessions/d0e570ee532a4881a9d6b5bef478ae46
Requested by: Ian Macartney

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/get-convex/rag/@convex-dev/rag@71

commit: dbb0df2

[devin-ai-integration]

Closing due to inactivity for more than 7 days. Configure here.