Prerequisites
You need:- A Gloo AI Studio account
- Your API key from the API Keys page. Keep it on your server and out of source control; see API Key Security
- A Publisher created with content uploaded in Gloo Studio
- PHP 8.0 or later, if you follow the PHP examples
What you’ll build
A comparison of non-grounded and grounded answers that shows you how RAG grounding works, in four steps:- Understand the hallucination problem (Step 1): A non-grounded request uses generic model knowledge and may hallucinate
- Ground on your publisher (Step 2): A grounded request uses your specific content, accurate and source-backed
- Compare side by side (Step 3): Run both approaches in one function
- Test your implementation (Step 4): Validate your setup with the Bezalel example, then adapt the code to your own content
Example: Bezalel Ministries
For this tutorial, we’ve cooked up a fictional organization called Bezalel Ministries. They’re a faith-based creative group who produce biblically-accurate artwork and educational resources. They’re delightful. We’ve created 5 sample documents covering everything from their hiring process to their educational programs and research methodology. Why a made-up org? It shows exactly how the API works without real-world baggage. Plus, Bezalel Ministries is more interesting than “Company X” or “Acme Corp”. What the comparison reveals:- Step 1 (Non-grounded): Generic hiring advice with no knowledge of Bezalel
- Step 2 (Publisher grounded): Accurate details about Bezalel’s 3-phase selection journey from their actual docs
Working Code Sample
Follow along with complete working examples in all 6 languages (JavaScript, TypeScript, Python, PHP, Go, Java). Includes the 5 Bezalel sample content files.Setup and testing instructions are below.
Step 1: Understanding the Hallucination Problem
Without grounding, when you ask about specific organizational information, the model relies on general knowledge and may:- Provide generic answers that don’t match your reality
- Make up plausible-sounding but incorrect information
- Say “I don’t have information” even though you’ve uploaded relevant content
Grounding narrows this problem substantially, but it does not close it. A grounded answer can still contain a quotation or a resource title that appears in none of the retrieved sources. Production applications add a verification step between generation and display. See Building Trustworthy Grounded Applications.
The Non-Grounded Request
This is a standard Completions V2 call:Step 2: Grounding on Your Publisher
Now ground the request on YOUR specific content.The Publisher Grounded Request
This adds two key changes from Step 1: the/grounded endpoint and the rag_publisher parameter:
sources_returned: true flag confirms RAG found and used relevant sources.
Why this query works: The Bezalel publisher contains a document titled “bezalel_hiring_process.txt” that describes their selection journey in detail. When you ground on this publisher, the RAG system retrieves this document before generating the response.For your own use case, design queries that match your uploaded content. If you upload product documentation, ask product questions. If you upload HR policies, ask HR questions.
Side-by-Side Comparison
Publisher and query examples
Publisher and query examples
Different content types require different query approaches:
Key Pattern: Your queries should directly relate to the information in your uploaded documents.
Step 3: Comparing Side-by-Side
The clearest way to show RAG’s value is to compare both approaches in one function:Example Output
Step 4: Test your implementation
This tutorial provides two testing paths:- Quick Start (Recommended): Test the Bezalel example to validate your setup
- Your Own Content: Adapt the code to use your publisher and content
Phase 1: Quick Start with Bezalel Example
First, run the provided Bezalel example to validate your setup.1
Set up
- Install dependencies for your language (see cookbook READMEs)
- Configure
.envwith your credentials: - Create the Bezalel publisher in Gloo Studio:
- Create a new publisher named “Bezalel” (exact name, case-sensitive)
- Upload the 5 sample content files from the cookbook’s
content/directory - Wait for all documents to show “Completed” status before proceeding
2
Run the comparison
Each language implementation includes a ready-to-run comparison demo:
3
Check what to look for
When testing with ANY publisher (Bezalel or your own):✅ Step 1 (Non-grounded):
- Generic response not specific to your content
- Example: “A typical hiring process involves…” (for any hiring query)
- Specific, accurate information from YOUR uploaded documents
sources_returned: true(if this is false, see troubleshooting)- Example: For Bezalel → “3-phase selection journey with calling alignment…”
- Example: For your product docs → “The enterprise plan is $X/month and includes…”
Phase 2: Adapt to Your Own Content
Once the Bezalel example works, adapt it to your own use case.1
Prepare your content
Before modifying code, ensure you have:
- Created a Publisher in Gloo Studio
- See Upload Files to Data Engine recipe for detailed instructions
- Uploaded relevant documents (PDFs, text files, Word docs, etc.)
- Upload content that answers the questions your users will ask
- Example: HR policies for HR questions, product docs for product questions
- Note your Publisher name (you’ll need this for the code)
2
Update the code
Modify two areas in the code:A. Update Environment VariablesIn your B. Update QueriesDesign queries that match your uploaded content:
.env file:3
Run and validate
Run your modified code using the same commands from Phase 1.Interpreting Results:✅ Success indicators:
- Step 2 shows
sources_returned: true - Step 2 response contains specific information from your documents
- Step 2 is noticeably more accurate than Step 1
- Check that your publisher name matches exactly (case-sensitive)
- Verify content is uploaded and indexed in Studio
- Ensure your queries are relevant to your content
- Try increasing
sources_limit(change 3 to 5 or 10)
4
Refine your queries
If results aren’t accurate:
- Make queries more specific: “What is the pricing?” → “What is the enterprise plan pricing for annual subscriptions?”
- Match content structure: If your document is titled “Installation Guide,” ask installation questions
- Test incrementally: Start with one query, verify it works, then add more
- Check sources: If available in the API response, inspect which documents were retrieved
Complete code
View Complete Code
Clone or browse the complete working examples for all 6 languages (JavaScript,
TypeScript, Python, PHP, Go, Java) with setup instructions and Bezalel content
files.
Troubleshooting
Publisher not found error
Publisher not found error
- Verify publisher name is exact match (case-sensitive) to Studio
- Confirm publisher exists at Gloo Studio
- Check you’re using the correct account/credentials
No sources returned
No sources returned
- Verify content is uploaded to the publisher you named in
rag_publisher, and has finished indexing in Studio - For the full checklist (indexing status, query fit,
sources_limit), see When Grounding Looks Wrong
Authentication errors
Authentication errors
Generic responses in grounded mode
Generic responses in grounded mode
If Step 2 (publisher grounded) responses still seem generic:
- Check
sources_returnedflag—should betruefor Step 2 - Verify you’re using the
rag_publisherparameter - For content and query checks, see When Grounding Looks Wrong
Step 2 isn't using my content
Step 2 isn't using my content
If Step 2 returns
sources_returned: false or generic responses:Check Publisher Name:- Publisher names are case-sensitive: “MyPublisher” ≠ “mypublisher”
- Verify exact name in Gloo Studio
- Check for typos in your code or
.envfile
sources_limit, and content quality are covered in When Grounding Looks Wrong.Take it further
Ideas for a production chatbot
Ideas for a production chatbot
Extend this recipe:
- Add streaming for real-time responses
- Implement conversation history
- Extract and display source citations
- Verify answers against their sources before displaying them
- Handle edge cases (no sources found, publisher not found)
- Add user feedback collection
- Adjust source limits: Use
sources_limitto control how many documents are retrieved - Search without generation: Use the Search API for RAG without completion
- Multi-turn conversations: Maintain context across multiple grounded queries
- Hybrid approaches: Mix grounded and non-grounded based on query type
Learn the concepts
Learn the concepts
- The Generation Step: keeping answers faithful to their sources
- Citations and Verification: showing sources and checking claims before display
More resources
More resources
- Grounded Completions API Reference - Full parameter details
- Authentication Tutorial - API key setup details
Next steps
To use your own content, follow Phase 2: Adapt to Your Own Content above to prepare and upload your content, update the code for your publisher, design effective queries, and validate and refine your results.Build Trustworthy Grounded Applications
Verify answers against their sources before displaying them.
Upload Files Tutorial
Set up Publishers and upload documents.
Completions V2 API Guide
Complete API documentation.
How RAG Actually Works
The retrieve, augment, generate steps behind this tutorial.

