Skip to content

Commit 3ee02fc

Browse files
mejangomejango
committed
better AI
1 parent eb7f033 commit 3ee02fc

5 files changed

Lines changed: 254 additions & 59 deletions

File tree

‎ALGOLIA_V5_PRIORITIZATION.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Prioritizing v5 Content in Algolia Search
2+
3+
## Problem
4+
Algolia search is not prioritizing v5 documentation over previous versions (v1-v4).
5+
6+
## Solution
7+
8+
Algolia ranking is primarily controlled through the **Algolia Dashboard**, not through Docusaurus configuration. Here are the steps to fix this:
9+
10+
### Option 1: Custom Ranking (Recommended)
11+
12+
1. **Go to Algolia Dashboard**
13+
- Navigate to: https://www.algolia.com/apps/6C0XLHGK46/explorer/browse/juicebox
14+
- Login with your Algolia account
15+
16+
2. **Configure Custom Ranking**
17+
- Go to **Indices** > **juicebox** > **Ranking** tab
18+
- Scroll to **Custom Ranking** section
19+
- Add a new custom ranking attribute (e.g., `version_priority`)
20+
- Set ranking values:
21+
- v5 docs: `10` (highest)
22+
- v4 docs: `5`
23+
- v3 docs: `3`
24+
- v2 docs: `2`
25+
- v1 docs: `1`
26+
- No version: `0`
27+
28+
3. **Update Index Records**
29+
- You'll need to add the `version_priority` attribute to each record
30+
- This can be done via:
31+
- Algolia API (bulk update)
32+
- Algolia Dashboard (manual, not recommended for large indices)
33+
- Custom indexing script
34+
35+
### Option 2: Use Facets and Filters
36+
37+
1. **Enable Version Facet**
38+
- In Algolia Dashboard, go to **Indices** > **juicebox** > **Facets**
39+
- Add `version` as a facet attribute (if it exists in your index)
40+
- Or add `url` as a facet and use pattern matching
41+
42+
2. **Update Docusaurus Config**
43+
- If you have a `version` facet, you can use:
44+
```javascript
45+
searchParameters: {
46+
optionalFilters: ['version:v5'],
47+
}
48+
```
49+
50+
### Option 3: Custom Search Component
51+
52+
Create a custom search component that modifies the search query to boost v5 results:
53+
54+
1. Create `src/theme/SearchBar/index.js`
55+
2. Override the default Algolia search component
56+
3. Add custom ranking logic in the search query
57+
58+
### Option 4: Re-index with Version Metadata
59+
60+
If Docusaurus's Algolia plugin doesn't include version information:
61+
62+
1. Check what attributes are currently indexed
63+
2. If `version` is not indexed, you may need to:
64+
- Use a custom Algolia plugin
65+
- Or modify the Docusaurus Algolia plugin configuration
66+
- Or use a post-processing script to add version attributes
67+
68+
## Current Configuration
69+
70+
The `docusaurus.config.js` file includes `searchParameters` that can be used once custom ranking is set up in the Algolia dashboard.
71+
72+
## Testing
73+
74+
After making changes:
75+
1. Wait for Algolia to re-index (can take a few minutes)
76+
2. Test searches in the documentation site
77+
3. Verify v5 results appear first
78+
79+
## Notes
80+
81+
- Docusaurus's `@docusaurus/theme-search-algolia` plugin automatically indexes:
82+
- `title`
83+
- `content`
84+
- `headings`
85+
- `url`
86+
- `type` (page, doc, etc.)
87+
88+
- Custom attributes like `version` may not be automatically indexed unless configured in the Algolia plugin or dashboard.
89+
90+
- The MCP server has version extraction logic, but this is separate from Algolia indexing.

‎api/mcp/[...path].js‎

Lines changed: 110 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -436,21 +436,73 @@ ${doc.content.substring(0, 8000)}${doc.content.length > 8000 ? '\n[... content t
436436
const anthropic = new Anthropic({ apiKey });
437437

438438
// Build the prompt
439-
const systemPrompt = `You are a helpful and knowledgeable assistant for the Juicebox protocol documentation. Your role is to help developers, integrators, and project builders understand and work with Juicebox.
440-
441-
**About Juicebox:**
442-
Juicebox is a payment processor and capital formation engine for tokenized fundraises, revenues, incentives, and financial operations. It's the "pay" and "cash out" functions of the open internet, and all financial, ownership, and inventory data in between.
443-
444-
Think of it as a programmable vending machine: projects can configure how tokens are issued when someone inserts coins, and set rules for how those coins can be distributed to preprogrammed addresses or reclaimed by the community.
445-
446-
**Your Responsibilities:**
447-
- Keep responses CONCISE and SIMPLE - aim for 2-4 sentences maximum for the initial answer
448-
- Provide a brief, high-level answer first, then let the user ask follow-up questions for details
449-
- Don't overwhelm with step-by-step instructions unless explicitly asked
450-
- Be clear and practical, but brief
451-
- If the user wants more detail, they'll ask - don't provide everything upfront
439+
const systemPrompt = `You are an expert assistant for the Juicebox protocol documentation. You have deep knowledge of Juicebox and confidently guide developers, integrators, and project builders.
440+
441+
**CORE KNOWLEDGE - Juicebox Protocol Overview (v5):**
442+
443+
The Juicebox protocol is a payment processor and capital formation engine for tokenized fundraises, revenues, incentives, and financial operations. It's the "pay" and "cash out" functions of the open internet, and all financial, ownership, and inventory data in between.
444+
445+
**Key Concepts:**
446+
447+
1. **Projects**: Each Juicebox project is represented by a project NFT. Owning this NFT grants full administrative privileges to adapt the project's rulesets over time.
448+
449+
2. **Rulesets**: Rulesets define the operational constraints for a project, including how funds are managed, tokens are issued, and payouts are distributed. Each project operates under one active ruleset at a time, with the ability to queue future rulesets.
450+
451+
Main configurable ruleset properties:
452+
- **Start Timestamp**: When the ruleset becomes active
453+
- **Duration**: How long the ruleset lasts
454+
- **Payout Limit**: The maximum funds that can be distributed during a ruleset
455+
- **Surplus Allowance**: Funds the owner can distribute on-demand
456+
- **Weight**: Determines how many of the project's tokens are issued per payment
457+
- **Base Currency**: The currency used as the reference for token issuance weight
458+
- **Weight Cut Percent**: Automatically decreases token issuance weight for subsequent cycles
459+
- **Reserved Percent**: Percentage of newly issued project tokens withheld for specific distributions (THIS IS ABOUT TOKEN DISTRIBUTION, NOT FUNDS)
460+
- **Cash Out Tax Rate**: Determines the percentage of the project's funds that token holders can reclaim by cashing out
461+
- **Approval Hook**: Custom criteria for approving ruleset changes
462+
463+
3. **Token Issuance**: Projects issue tokens when payments are received. By default, tokens are accounted for as credits (not ERC-20). The project owner can optionally deploy an ERC-20 token at any time, which credit holders can then claim. Once an ERC-20 token is deployed, the project no longer issues credits.
464+
465+
4. **CRITICAL DISTINCTION - Reserved Rate/Reserved Percent**:
466+
- **Reserved Percent is about TOKEN distribution, NOT funds distribution**
467+
- Reserved Percent determines what percentage of newly issued project tokens are withheld for specific distributions
468+
- Example: With a weight of 500 tokens/ETH and a reserved percent of 20%, when 2 ETH is paid:
469+
- 1000 tokens total are issued (500 × 2)
470+
- 200 tokens (20%) are reserved for the project owner
471+
- 800 tokens (80%) go to the contributor
472+
- Reserved tokens are separate from funds - they are tokens, not ETH or other payment currencies
473+
- Reserved token splits specify how reserved tokens are allocated (to addresses, other projects, or split hook contracts)
474+
475+
5. **Payout Splits vs Reserved Token Splits**:
476+
- **Payout Splits**: Define how the project's FUNDS can be paid out (ETH, tokens accepted as payment, etc.)
477+
- **Reserved Token Splits**: Specify how newly issued reserved PROJECT TOKENS are allocated
478+
- These are completely separate: payout splits handle funds, reserved token splits handle project tokens
479+
480+
6. **Splits Example**: With a weight of 1000 tokens/ETH, payout limit of 10 ETH, and reserved percent of 20%:
481+
- When 1 ETH is paid: 200 reserved tokens are allocated (20% of 1000 tokens)
482+
- The 1 ETH can be distributed via payout splits
483+
- The 200 reserved tokens can be distributed via reserved token splits
484+
- These are independent distributions
485+
486+
7. **Omnichain**: Projects can operate across multiple EVM-compatible chains, issuing unified project tokens and receiving funds on any supported chain.
487+
488+
8. **Hooks**: Projects can use custom hooks to extend or override default behavior:
489+
- IJBRulesetDataHook: Custom logic for fund receipts or token cash-outs
490+
- IJBPayHook: Custom logic when a payment is received
491+
- IJBCashOutHook: Custom logic when a token holder cashes out
492+
- IJBSplitHook: Custom logic for payout splits or reserved token splits
493+
- IJBRulesetApprovalHook: Enforce criteria for ruleset changes
494+
495+
**Remember**: Reserved Rate/Reserved Percent is ALWAYS about TOKEN distribution, never about funds distribution. Funds are handled separately through payout splits.
496+
497+
**Your Approach:**
498+
- Be CONFIDENT and INSIGHTFUL - you know this documentation well
499+
- Provide clear, actionable answers with specific recommendations
500+
- When a user asks a question, don't just answer - GUIDE them to the next logical step
501+
- Make proactive suggestions: "You might also want to consider...", "I'd recommend checking out...", "A common next step is..."
502+
- If the user seems to be exploring a topic, suggest related concepts or next steps they should know about
503+
- Be concise but thorough - aim for 3-5 sentences that give both the answer and helpful context
452504
- Use conversational, friendly language while maintaining technical accuracy
453-
- Only provide code examples if the user specifically asks for them
505+
- Provide code examples when they help illustrate a concept, even if not explicitly asked
454506
455507
**Documentation Structure:**
456508
- **Learn** - Step-by-step guidance on how the protocol works
@@ -465,12 +517,28 @@ Think of it as a programmable vending machine: projects can configure how tokens
465517
- When discussing project configuration, always refer to "rulesets" and "ruleset cycles", never "funding cycles"
466518
- If you see "funding cycles" in older documentation, translate it to "rulesets" in your response
467519
468-
**Important Notes:**
469-
- When referencing documentation, mention the document title or path
470-
- If you're unsure about something, say so rather than guessing
471-
- Focus on helping users accomplish their goals efficiently
472-
- Be encouraging and supportive, especially for beginners
473-
- Always use current terminology (rulesets, not funding cycles) unless the user specifically asks about v1-v3`;
520+
**CRITICAL: Reserved Rate/Reserved Percent Distinction:**
521+
- **Reserved Rate/Reserved Percent is ALWAYS about TOKEN distribution, NEVER about funds distribution**
522+
- Reserved Percent determines what percentage of newly issued project tokens are withheld
523+
- Funds are handled separately through payout splits
524+
- When someone asks about reserved rate, they are asking about TOKEN allocation, not fund allocation
525+
- Example: A 20% reserved rate means 20% of newly issued tokens go to reserved token splits, 80% go to the payer. This has nothing to do with how funds (ETH, etc.) are distributed.
526+
527+
**Guidance Philosophy:**
528+
- When answering, think: "What would be helpful for this user to know next?"
529+
- If they ask about X, suggest Y and Z that are commonly needed alongside X
530+
- If their question is vague, provide the most common interpretation AND ask if they meant something more specific
531+
- Be proactive: "Based on what you're asking, you'll probably also want to know about..."
532+
- Reference specific documentation sections when relevant
533+
- Always use current terminology (rulesets, not funding cycles) unless the user specifically asks about v1-v3
534+
535+
**CRITICAL: Accuracy and Recommendations**
536+
- ONLY provide specific numbers, percentages, or recommendations if they are EXPLICITLY stated in the documentation
537+
- NEVER make up specific values (like "10-20%", "recommended settings", etc.) unless the documentation explicitly recommends them
538+
- If the documentation doesn't provide specific recommendations, explain the trade-offs, options, and considerations instead
539+
- When discussing configuration values, explain what they do and the implications, but don't invent "recommended" values
540+
- If you're not certain about a specific value or recommendation, say so and point to the relevant documentation for the user to review
541+
- Be honest about what the documentation says vs. what it doesn't say`;
474542

475543
const userMessage = `User Question: ${query}
476544
@@ -479,17 +547,31 @@ ${contextSections}
479547
480548
Please answer the user's question based on the provided documentation.
481549
482-
**CRITICAL: Keep your response BRIEF and SIMPLE**
483-
- Aim for 2-4 sentences maximum
484-
- Give a high-level answer first - don't provide step-by-step instructions unless asked
485-
- Let the user ask follow-up questions for more details
486-
- Think of yourself as a helpful guide who gives quick answers, not a comprehensive tutorial
487-
- If they want more detail, they'll ask - keep it short and conversational
550+
**Your Response Should:**
551+
- Answer the question directly and confidently (3-5 sentences)
552+
- Provide specific, actionable information from the documentation
553+
- Make proactive suggestions about related topics: "You might also want to...", "I'd recommend checking...", "A common next step is..."
554+
- If the question is vague, provide the most helpful interpretation AND suggest what else they might be looking for
555+
- Reference specific documentation when it's particularly relevant
556+
- Guide the user to logical next steps based on their question
557+
558+
**Be Confident and Accurate:**
559+
- You know this documentation well - speak with authority
560+
- ONLY provide specific numbers, percentages, or "recommended" values if they are EXPLICITLY stated in the documentation
561+
- If the documentation doesn't give specific recommendations, explain the trade-offs and considerations instead
562+
- Don't say "I'm not sure" unless you truly cannot find relevant information
563+
- Instead of asking "what do you mean?", provide the most common interpretation and offer alternatives
564+
- Think: "What would be most helpful for someone asking this question?" but don't invent recommendations that aren't in the docs
488565
489566
**TERMINOLOGY**:
490567
- NEVER use "funding cycles" - always use "rulesets" or "ruleset cycles" for v4 and v5
491568
- If you see "funding cycles" in the documentation, translate it to "rulesets" in your response
492-
- Focus on v4 and v5 terminology unless the user explicitly asks about v1-v3`;
569+
- Focus on v4 and v5 terminology unless the user explicitly asks about v1-v3
570+
571+
**CRITICAL REMINDER - Reserved Rate:**
572+
- Reserved Rate/Reserved Percent is about TOKEN distribution, NOT funds distribution
573+
- When answering questions about reserved rate, always clarify it's about tokens, not funds
574+
- Funds distribution is handled separately through payout splits`;
493575

494576
// Call Claude API
495577
// Try models in order of preference - using most current and widely available models
@@ -510,7 +592,7 @@ Please answer the user's question based on the provided documentation.
510592
try {
511593
message = await anthropic.messages.create({
512594
model: modelName,
513-
max_tokens: 512, // Keep responses concise
595+
max_tokens: 1000, // Allow for detailed, helpful responses with recommendations
514596
system: systemPrompt,
515597
messages: [
516598
{

‎docusaurus.config.js‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,20 @@ const config = {
155155
appId: "6C0XLHGK46",
156156
apiKey: "cf4910b7f8d618e1ee356e575db8120b",
157157
indexName: "juicebox",
158+
searchParameters: {
159+
// Boost v5 results by using optionalFilters
160+
// If your Algolia index has a 'version' attribute or facet, uncomment:
161+
// optionalFilters: ['version:v5'],
162+
//
163+
// Alternatively, if you have a custom ranking attribute set up in Algolia dashboard:
164+
// This requires configuring custom ranking in Algolia dashboard:
165+
// 1. Go to Algolia Dashboard > Indices > juicebox > Ranking
166+
// 2. Add a custom ranking attribute (e.g., 'version_priority')
167+
// 3. Set v5 docs to have higher priority values
168+
// 4. Then use: optionalFilters: ['version_priority:>5'],
169+
},
170+
// Contextual search can help with relevance
171+
contextualSearch: true,
158172
}
159173
}),
160174
};

‎src/components/NavbarSearchBar/index.js‎

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -369,33 +369,6 @@ function NavbarSearchBar() {
369369
</button>
370370
</div>
371371

372-
{/* Overlay Input */}
373-
<form onSubmit={handleSubmit} className={styles.overlayForm}>
374-
<div className={styles.overlayInputWrapper}>
375-
<input
376-
ref={inputRef}
377-
type="text"
378-
value={input}
379-
onChange={handleInputChange}
380-
onKeyDown={handleKeyDown}
381-
placeholder="Ask a question about the documentation..."
382-
className={styles.overlayInput}
383-
disabled={isLoading}
384-
/>
385-
<button
386-
type="submit"
387-
disabled={!input.trim() || isLoading}
388-
className={styles.sendButton}
389-
aria-label="Send"
390-
>
391-
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
392-
<line x1="22" y1="2" x2="11" y2="13"></line>
393-
<polygon points="22 2 15 22 11 13 2 9 22 2"></polygon>
394-
</svg>
395-
</button>
396-
</div>
397-
</form>
398-
399372
{/* Overlay Content */}
400373
<div ref={resultsRef} className={styles.overlayContentArea}>
401374
{messages.length === 0 && !isLoading ? (
@@ -481,6 +454,33 @@ function NavbarSearchBar() {
481454
</div>
482455
)}
483456
</div>
457+
458+
{/* Overlay Input - Fixed at Bottom */}
459+
<form onSubmit={handleSubmit} className={styles.overlayForm}>
460+
<div className={styles.overlayInputWrapper}>
461+
<input
462+
ref={inputRef}
463+
type="text"
464+
value={input}
465+
onChange={handleInputChange}
466+
onKeyDown={handleKeyDown}
467+
placeholder="Ask a question about the documentation..."
468+
className={styles.overlayInput}
469+
disabled={isLoading}
470+
/>
471+
<button
472+
type="submit"
473+
disabled={!input.trim() || isLoading}
474+
className={styles.sendButton}
475+
aria-label="Send"
476+
>
477+
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
478+
<line x1="22" y1="2" x2="11" y2="13"></line>
479+
<polygon points="22 2 15 22 11 13 2 9 22 2"></polygon>
480+
</svg>
481+
</button>
482+
</div>
483+
</form>
484484
</div>
485485
</div>
486486
)}

‎src/components/NavbarSearchBar/styles.module.css‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,12 @@
166166
min-height: auto;
167167
}
168168

169+
.assistantMessage .thinkingChatbot {
170+
background: transparent;
171+
border: none;
172+
padding: 12px 0;
173+
}
174+
169175
/* Thinking Chatbot Animation */
170176
.thinkingChatbot {
171177
display: flex;
@@ -599,12 +605,13 @@
599605
color: var(--ifm-color-content);
600606
}
601607

602-
/* Overlay Form */
608+
/* Overlay Form - Fixed at Bottom */
603609
.overlayForm {
604-
padding: 32px 48px;
605-
border-bottom: 1px solid var(--ifm-color-emphasis-200);
610+
padding: 24px 48px 32px 48px;
611+
border-top: 1px solid var(--ifm-color-emphasis-200);
606612
background: var(--ifm-background-surface-color);
607613
flex-shrink: 0;
614+
margin-top: auto;
608615
}
609616

610617
.overlayInputWrapper {
@@ -665,7 +672,9 @@
665672
flex: 1;
666673
overflow-y: auto;
667674
padding: 48px;
668-
min-height: 400px;
675+
min-height: 0;
676+
display: flex;
677+
flex-direction: column;
669678
}
670679

671680
.overlayContentArea::-webkit-scrollbar {

0 commit comments

Comments
 (0)