Add CopilotKit retrieval integration cookbook example by PrinceThummar011 · Pull Request #367 · usemoss/moss

PrinceThummar011 · 2026-07-10T07:07:51Z

Summary

Adds a cookbook example demonstrating how to ground CopilotKit in-app
copilots with Moss's sub-10ms retrieval, so React apps can answer
questions using the user's own data.

Closes #340

What's included

examples/cookbook/copilotkit/ — a minimal working example showing:
- A Moss retrieval action/hook that queries a Moss index and returns
  results CopilotKit can ground responses on
- A small CopilotKit-powered React component wired to the retrieval
  action
- README with setup steps, use case, and how the integration works
Environment variables used for Moss project ID / key / index name
(no secrets committed)

Why

React apps using CopilotKit need a way to answer from private/custom
data instead of relying only on the model's built-in knowledge. This
example follows the same pattern as the existing Vercel AI SDK
integration and the daytona cookbook example already in this repo.

Testing

Installed dependencies fresh and ran the example end-to-end twice
(once before final cleanup, once after) to confirm nothing broke
Verified retrieval results are correctly passed into CopilotKit's
response grounding
Confirmed no console errors, no hardcoded secrets, and README steps
work from a clean clone

Notes for reviewers

Structure mirrors examples/cookbook/daytona/ for consistency with
other cookbook examples in the repo.

CLAassistant · 2026-07-10T07:07:59Z

All committers have signed the CLA.

Copilot

Pull request overview

Adds a new self-contained cookbook example under examples/cookbook/copilotkit/ demonstrating how to ground a CopilotKit in-app copilot using Moss retrieval via a secure Next.js App Router API route, with a mock fallback for running without credentials.

Changes:

Introduces a Next.js App Router app with a CopilotKit runtime endpoint and a Moss query endpoint (mock + real mode).
Adds a reusable useMossRetrieval hook wiring CopilotKit actions to the Moss query route.
Provides a dashboard-style UI plus setup docs and environment templates for quick local iteration.

Reviewed changes

Copilot reviewed 12 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
examples/cookbook/copilotkit/tsconfig.json	TypeScript configuration for the Next.js cookbook project.
examples/cookbook/copilotkit/README.md	Setup + usage documentation describing the CopilotKit ↔ Moss handoff.
examples/cookbook/copilotkit/package.json	Declares the example’s Next/CopilotKit/Moss dependencies and scripts.
examples/cookbook/copilotkit/next.config.ts	Configures Next.js server externals for Moss native bindings.
examples/cookbook/copilotkit/next-env.d.ts	Next.js TypeScript ambient type references for the cookbook.
examples/cookbook/copilotkit/app/use-moss-retrieval.ts	Client hook registering the CopilotKit retrieval action and calling `/api/moss/query`.
examples/cookbook/copilotkit/app/page.tsx	Interactive dashboard UI + grounded CopilotChat integration.
examples/cookbook/copilotkit/app/layout.tsx	App layout and global style imports.
examples/cookbook/copilotkit/app/globals.css	Dark-theme styling and CopilotKit UI overrides.
examples/cookbook/copilotkit/app/api/moss/query/route.ts	Server-side Moss query endpoint with mock fallback and response shaping.
examples/cookbook/copilotkit/app/api/copilotkit/route.ts	CopilotKit runtime endpoint backed by OpenAI.
examples/cookbook/copilotkit/.gitignore	Ignores node/Next build artifacts and local env.
examples/cookbook/copilotkit/.env.example	Documents required/optional environment variables for the cookbook.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated 5 comments.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated 5 comments.

…racy

Copilot

Pull request overview

Copilot reviewed 13 out of 15 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 13 out of 15 changed files in this pull request and generated 3 comments.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 13 out of 15 changed files in this pull request and generated 3 comments.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

PrinceThummar011 · 2026-07-15T13:29:38Z

Hi @HarshaNalluru @r4ghu — this PR has gone through several rounds of Copilot AI review and feedback has been addressed (input validation, logging, docs accuracy, etc. across the last few commits). The Copilot re-review attempt just failed due to a quota limit on my end, but I don't think that should block things further.

Could one of you take a look when you get a chance? It's currently blocked on needing at least 1 approving review from a code owner. Happy to address any additional feedback quickly. Thanks!

github-actions · 2026-07-25T02:29:43Z

+  try {
+    const { searchParams } = new URL(request.url);
+    const query = (searchParams.get("query") ?? "").trim();
+    const indexName = searchParams.get("indexName") || process.env.MOSS_INDEX_NAME;


BLOCKING This lets a browser request choose which secret-backed Moss index to query:

const indexName = searchParams.get("indexName") || process.env.MOSS_INDEX_NAME;

Anyone who can reach /api/moss/query can query any index in the configured Moss project if they know or guess its name. Keep the index selection on the server side, or validate it against a server-side allowlist after authenticating the user, e.g. const indexName = process.env.MOSS_INDEX_NAME;.

github-actions · 2026-07-25T02:29:43Z

+    }
+
+    // MOCK MODE FALLBACK
+    if (isMockMode || !mossClient) {


BLOCKING This falls back to sample data even when real Moss credentials were supplied but client initialization failed:

if (isMockMode || !mossClient) {

That can make a misconfigured production demo answer with the built-in refund/contact mock docs instead of failing visibly. Only use mock mode when credentials are actually absent/placeholders; if !mossClient after real credentials, return a 500 such as MossClient failed to initialize.

github-actions · 2026-07-25T02:29:44Z

Codex review

The new cookbook example is close, but the Moss query route currently weakens the server-side security boundary and can silently serve mock data when real Moss setup is broken.

Add CopilotKit retrieval integration cookbook example (usemoss#340)

4b900af

PrinceThummar011 requested a review from HarshaNalluru as a code owner July 10, 2026 07:07

Copilot AI review requested due to automatic review settings July 10, 2026 07:07

PrinceThummar011 requested a review from r4ghu as a code owner July 10, 2026 07:07

Copilot started reviewing on behalf of PrinceThummar011 July 10, 2026 07:08 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Potential fix for pull request finding

0d01af9

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 10, 2026 07:12

Copilot started reviewing on behalf of PrinceThummar011 July 10, 2026 07:13 View session

PrinceThummar011 changed the title ~~Add CopilotKit retrieval integration cookbook example (#340)~~ Add CopilotKit retrieval integration cookbook example Jul 10, 2026

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Potential fix for pull request finding

81658b5

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 10, 2026 07:21

Copilot started reviewing on behalf of PrinceThummar011 July 10, 2026 07:21 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Address Copilot review feedback: input validation, logging, docs accu…

ac78592

…racy

Copilot AI review requested due to automatic review settings July 10, 2026 09:01

Copilot started reviewing on behalf of PrinceThummar011 July 10, 2026 09:01 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

PrinceThummar011 requested a review from Copilot July 15, 2026 13:00

Copilot started reviewing on behalf of PrinceThummar011 July 15, 2026 13:01 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

Comment thread examples/cookbook/copilotkit/app/api/moss/query/route.ts

Comment thread examples/cookbook/copilotkit/app/page.tsx

Comment thread examples/cookbook/copilotkit/README.md Outdated

Potential fix for pull request finding

46b46d7

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 15, 2026 13:19

Copilot started reviewing on behalf of PrinceThummar011 July 15, 2026 13:20 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

Comment thread examples/cookbook/copilotkit/package.json

Comment thread examples/cookbook/copilotkit/app/page.tsx

Comment thread examples/cookbook/copilotkit/README.md

Potential fix for pull request finding

4f1d726

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 15, 2026 13:24

Copilot AI reviewed Jul 15, 2026

HarshaNalluru closed this Jul 25, 2026

HarshaNalluru reopened this Jul 25, 2026

github-actions Bot reviewed Jul 25, 2026

View reviewed changes

Uh oh!

Conversation

PrinceThummar011 commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's included

Why

Testing

Notes for reviewers

Uh oh!

CLAassistant commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

PrinceThummar011 commented Jul 15, 2026

Uh oh!

github-actions Bot Jul 25, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 25, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 25, 2026

Codex review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

PrinceThummar011 commented Jul 10, 2026 •

edited

Loading

CLAassistant commented Jul 10, 2026 •

edited

Loading