[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_473":474,"_475":476},"routes/_app.x.$handle.$name",{"_94":93,"_31":43,"_102":84,"_26":103,"_13":14,"_104":-5,"_11":105,"_106":107,"_108":109,"_110":111,"_112":113,"_20":-5,"_114":-5,"_115":-5,"_116":24,"_117":118,"_119":47,"_120":-5,"_121":-5,"_122":123},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_41":42,"_31":43,"_36":44,"_45":-5,"_46":47,"_48":49,"_50":49,"_51":-5,"_52":-5,"_18":53,"_54":55,"_56":47,"_57":-5,"_58":-5,"_59":60,"_61":62,"_63":-5,"_64":-5,"_65":-5,"_66":-5,"_67":68,"_69":68,"_70":71,"_72":71,"_73":71,"_74":68,"_75":68,"_76":77,"_78":79,"_80":81,"_82":24},"version",56,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":-7,"_23":24,"_25":24,"_26":27,"_28":27},"file",{"_29":30,"_31":32,"_33":20,"_34":35,"_36":37,"_38":14,"_39":40,"_23":24},"previous","deleted",false,"deletedHere","path","answer/QUICK-START.md","latestPath","fileId","7f58d680-b9ca-11f0-afaf-0224a6c84d84","name","QUICK-START.md","fileType","content","# Answer Strategies - Quick Start Guide\n\nThis guide will help you quickly get started with answer strategies for RAG-based question answering.\n\n## What Are Answer Strategies?\n\nAnswer strategies implement **Retrieval-Augmented Generation (RAG)** - they search documentation, retrieve relevant pages, and use an LLM to generate answers to user questions.\n\n## Quick Test\n\n### 1. Run Tests Locally (Recommended)\n\n```bash\n# Run comprehensive test suite with timing breakdown\ndeno task answer\n```\n\nThis will:\n- Load test questions from `testing/questions.ts`\n- Run each question through the active answer strategy\n- Show detailed timing breakdown (search, context prep, LLM call)\n- Display search results used for context\n- Show generated answers\n- Provide summary statistics\n\n### 2. Test via API Endpoints\n\n#### Start the Server\n\n```bash\ndeno task serve\n```\n\n#### Test Single Questions\n\n```bash\n# Basic question\ncurl \"http://localhost:8000/answer?q=How+do+I+use+the+Groq+API\"\n\n# With options\ncurl \"http://localhost:8000/answer?q=What+models+are+available&maxContextPages=3\"\n\n# Get strategy info\ncurl \"http://localhost:8000/answer/info\"\n\n# Run test suite via API\ncurl \"http://localhost:8000/answer/test\"\n```\n\n## How It Works\n\n### Step-by-Step Process\n\n1. **User asks a question**: \"How do I authenticate with the Groq API?\"\n\n2. **Search** (50-500ms): The active search strategy finds relevant docs\n ```\n → Search query: \"authenticate groq api\"\n → Returns: Top 10 matching pages ranked by relevance\n ```\n\n3. **Retrieve** (fast, from cache): Get full content for top 5 pages\n ```\n → Loads content from latest.json (local cache)\n → Each page limited to ~2000 tokens\n ```\n\n4. **Format** (<50ms): Package docs as LLM context\n ```\n → Formats pages with titles, URLs, and content\n → Adds system prompt with instructions\n → Creates user prompt with question\n ```\n\n5. **Generate** (500-3000ms): LLM generates answer\n ```\n → Calls Groq API with Llama 3.3 70B\n → Returns markdown-formatted answer\n → Includes citations and examples from docs\n ```\n\n## Understanding the Response\n\n```json\n{\n \"answer\": \"To authenticate with the Groq API...\",\n \"query\": \"How do I authenticate with the Groq API?\",\n \"searchResults\": [\n {\n \"path\": \"api/authentication\",\n \"url\": \"https://console.groq.com/docs/api/authentication\",\n \"title\": \"Authentication\",\n \"score\": 92.5\n }\n ],\n \"contextUsed\": 5,\n \"totalTokens\": 8500,\n \"metadata\": {\n \"strategy\": \"llama-3.3-70b-default\",\n \"model\": \"llama-3.3-70b-versatile\",\n \"temperature\": 0.3,\n \"searchResultsCount\": 10,\n \"timings\": {\n \"search\": 45.2,\n \"contextPrep\": 5.1,\n \"llm\": 1250.3,\n \"total\": 1300.6\n }\n }\n}\n```\n\n### Key Fields\n\n- **answer**: The LLM-generated answer (markdown formatted)\n- **query**: Your original question\n- **searchResults**: Top pages used as context (with scores)\n- **contextUsed**: Number of pages actually sent to the LLM\n- **totalTokens**: Approximate tokens in the context\n- **metadata.timings**: Performance breakdown\n\n## Switching Strategies\n\n### Current Strategy\n\nThe active strategy is set in `answer/index.ts`:\n\n```typescript\n// Default: Llama 3.3 70B with up to 5 doc pages\nimport { answerStrategy } from \"./llama-3.3-70b-default.ts\";\n```\n\n### Available Strategies\n\nCurrently available:\n- ✅ **llama-3.3-70b-default**: Balanced quality and speed\n\nComing soon (you can implement these!):\n- ⚡ **llama-3.1-8b-fast**: Faster responses with smaller model\n- 📚 **mixtral-8x7b-extended**: More context with larger model\n- 💻 **llama-3.3-70b-code**: Optimized for code examples\n- 🔗 **citation-mode**: Includes specific citations\n\n### Switching\n\n1. Comment out current strategy in `answer/index.ts`\n2. Uncomment the strategy you want to use\n3. Restart the server\n\n```typescript\n// answer/index.ts\n\n// Comment out default\n// import { answerStrategy } from \"./llama-3.3-70b-default.ts\";\n\n// Use fast strategy instead\nimport { answerStrategy } from \"./llama-3.1-8b-fast.ts\";\n```\n\n## Query Parameters\n\n### Required\n\n- **q**: The question to answer\n ```bash\n ?q=How+do+I+use+streaming\n ```\n\n### Optional\n\n- **limit**: Max search results (default: 10)\n ```bash\n ?limit=20\n ```\n\n- **minScore**: Minimum search score 0-100 (default: 0)\n ```bash\n ?minScore=50\n ```\n\n- **maxContextPages**: Pages to send to LLM (default: 5)\n ```bash\n ?maxContextPages=3\n ```\n\n- **temperature**: LLM temperature 0-1 (default: 0.3)\n ```bash\n ?temperature=0.5\n ```\n\n- **model**: Override the model (optional)\n ```bash\n ?model=llama-3.1-8b-instant\n ```\n\n### Example Combinations\n\n```bash\n# Fast mode: fewer pages, instant model\ncurl \"http://localhost:8000/answer?q=What+is+Groq&maxContextPages=2&model=llama-3.1-8b-instant\"\n\n# High quality: more pages, higher threshold\ncurl \"http://localhost:8000/answer?q=How+to+implement+retry+logic&limit=20&minScore=60&maxContextPages=7\"\n\n# Creative mode: higher temperature\ncurl \"http://localhost:8000/answer?q=Ideas+for+using+Groq+API&temperature=0.8\"\n```\n\n## Common Question Types\n\n### Factual Questions\n\n**Good for**: Quick facts, definitions, model names\n\n```bash\ncurl \"http://localhost:8000/answer?q=What+models+does+Groq+support\"\n```\n\n**Best settings**: Default (5 pages, temp 0.3)\n\n### How-To Questions\n\n**Good for**: Implementation guides, step-by-step instructions\n\n```bash\ncurl \"http://localhost:8000/answer?q=How+do+I+implement+streaming\"\n```\n\n**Best settings**: More pages (6-8), low temp (0.2-0.3)\n\n### Code Examples\n\n**Good for**: Requesting code snippets\n\n```bash\ncurl \"http://localhost:8000/answer?q=Show+me+a+Python+example+of+calling+the+API\"\n```\n\n**Best settings**: Code-focused strategy (when available), temp 0.3\n\n### Comparison Questions\n\n**Good for**: Comparing models, features, approaches\n\n```bash\ncurl \"http://localhost:8000/answer?q=Difference+between+Llama+3.1+and+3.3\"\n```\n\n**Best settings**: More pages (7-10), temp 0.3\n\n### Complex Questions\n\n**Good for**: Multi-part questions requiring reasoning\n\n```bash\ncurl \"http://localhost:8000/answer?q=How+to+build+a+chatbot+with+streaming+and+conversation+history\"\n```\n\n**Best settings**: More pages (8-10), 70B+ model, temp 0.4\n\n## Troubleshooting\n\n### No Answer Generated\n\n**Problem**: Returns error or empty answer\n\n**Possible causes**:\n- No search results found\n- GROQ_API_KEY not set\n- Rate limit exceeded\n\n**Solution**:\n```bash\n# Check if search works\ncurl \"http://localhost:8000/search?q=your+question\"\n\n# Verify API key\necho $GROQ_API_KEY\n\n# Check strategy info\ncurl \"http://localhost:8000/answer/info\"\n```\n\n### Poor Answer Quality\n\n**Problem**: Answer is vague, incorrect, or unhelpful\n\n**Possible causes**:\n- Search results not relevant\n- Not enough context (too few pages)\n- Temperature too high\n\n**Solutions**:\n```bash\n# Check search results first\ncurl \"http://localhost:8000/search?q=your+question&limit=10\"\n\n# Increase context\ncurl \"http://localhost:8000/answer?q=your+question&maxContextPages=8\"\n\n# Lower temperature\ncurl \"http://localhost:8000/answer?q=your+question&temperature=0.2\"\n\n# Increase search quality threshold\ncurl \"http://localhost:8000/answer?q=your+question&minScore=60\"\n```\n\n### Slow Responses\n\n**Problem**: Takes >5 seconds to respond\n\n**Possible causes**:\n- Slow search strategy\n- Too many pages in context\n- Large model\n\n**Solutions**:\n```bash\n# Use fewer pages\ncurl \"http://localhost:8000/answer?q=your+question&maxContextPages=3\"\n\n# Switch to faster model\ncurl \"http://localhost:8000/answer?q=your+question&model=llama-3.1-8b-instant\"\n\n# Check timing breakdown in response metadata\n```\n\n## Creating Your Own Strategy\n\n### 1. Copy the Template\n\n```bash\ncp answer/llama-3.3-70b-default.ts answer/my-custom-strategy.ts\n```\n\n### 2. Modify Configuration\n\n```typescript\n// Change these constants\nconst DEFAULT_MODEL = \"your-preferred-model\";\nconst DEFAULT_MAX_CONTEXT_PAGES = 3; // Adjust as needed\nconst DEFAULT_TEMPERATURE = 0.5;\nconst MAX_TOKENS_PER_PAGE = 1000; // Adjust as needed\n```\n\n### 3. Customize System Prompt (Optional)\n\n```typescript\nimport { DEFAULT_SYSTEM_PROMPT } from \"./utils.ts\";\n\n// Or create your own:\nconst CUSTOM_SYSTEM_PROMPT = `You are a helpful assistant that...`;\n```\n\n### 4. Update Strategy Info\n\n```typescript\nexport const answerStrategy: AnswerStrategy = {\n name: \"my-custom-strategy\",\n description: \"What makes your strategy special\",\n answer: async (query: string, options: AnswerOptions = {}) => {\n // Your implementation\n },\n};\n```\n\n### 5. Activate Your Strategy\n\nEdit `answer/index.ts`:\n\n```typescript\nimport { answerStrategy } from \"./my-custom-strategy.ts\";\n```\n\n### 6. Test It\n\n```bash\ncurl \"http://localhost:8000/answer/info\" # Verify active strategy\ncurl \"http://localhost:8000/answer?q=test+question\"\n```\n\n## Performance Tips\n\n### Optimize for Speed\n\n1. Use faster models (8B instead of 70B)\n2. Reduce context pages (2-3 instead of 5)\n3. Use faster search strategy\n4. Lower token limits per page\n\n### Optimize for Quality\n\n1. Use larger models (70B+)\n2. Increase context pages (7-10)\n3. Use higher search score thresholds\n4. Include more search results to choose from\n\n### Balance Both\n\n1. Start with default (5 pages, 70B, temp 0.3)\n2. Monitor timing breakdown in responses\n3. Adjust based on question complexity\n4. Cache common questions (future enhancement)\n\n## Next Steps\n\n1. ✅ Test the default strategy\n2. ✅ Try different query parameters\n3. ✅ Check the README.md for more details\n4. ⚡ Create a fast strategy for simple questions\n5. 📚 Create an extended strategy for complex questions\n6. 🔧 Customize system prompts for your use case\n7. 📊 Build a testing harness (like `/search/test`)\n\n## Resources\n\n- **Search Strategies**: See `/search/` for how document retrieval works\n- **Groq Models**: https://console.groq.com/docs/models\n- **API Reference**: https://console.groq.com/docs/api-reference\n\n## Questions?\n\nCheck out:\n- `answer/README.md` - Detailed documentation\n- `answer/types.ts` - Type definitions\n- `answer/utils.ts` - Helper functions\n- `main.tsx` - How endpoints are implemented\n\n","createdAt",["D",1762293981932],"branchVersion","branchId","632d0edc-2793-11f0-9d52-569c3dd06744","id","632cc576-2793-11f0-9d52-569c3dd06744","groq-docs",["D",1746217442601],"deletedAt","legacyEnvVars",true,"privacy","public","httpPrivacy","description","imageUrl","a8270e74-6479-475a-8025-9b69544ee0e7","pinnedFileId","632eed24-2793-11f0-9d52-569c3dd06744","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","8319defa-6e1a-46d4-ba66-2114ffd3360b","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_94":93,"_101":97},"org",{"_94":93,"_95":-5,"_96":97,"_18":53,"_98":99,"_100":24},"branch",{"_13":83,"_31":84,"_41":40,"_85":42,"_86":-5,"_87":-5,"_88":-5,"_89":-5,"_90":-5,"_91":43,"_92":93},"isOwned",105,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","yawnxyz","handle","displayName","avatar","https://images.clerk.dev/oauth_github/img_2NnaHhpxNuH1xWRIRjQNoo16TVc.jpeg","tier","pro","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_41":42,"_31":43,"_36":469,"_45":-5,"_46":47,"_48":49,"_50":49,"_51":-5,"_52":-5,"_18":53,"_54":55,"_56":47,"_57":-5,"_58":-5,"_59":60,"_61":62,"_63":-5,"_64":-5,"_65":-5,"_66":-5,"_67":68,"_69":68,"_70":71,"_72":71,"_73":71,"_74":68,"_75":68,"_76":470,"_78":471,"_80":472,"_82":24},"tree",[250,255,256,268,273,274,275,276,277,278,279,280,281,282],"files",[250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,277,278,279,280,281,282],"counts",{"_240":60,"_241":161,"_242":60,"_243":244,"_245":246},"contents",[124,125,126,127,128,129,130,131,132,133,134,135,136,137],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_41":234,"_31":235,"_29":236,"_141":-5,"_39":40,"_38":237,"_143":47,"_36":238,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_26":239},{"_41":228,"_31":229,"_29":230,"_141":-5,"_39":40,"_38":231,"_143":47,"_36":232,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_26":233},{"_41":222,"_31":223,"_29":224,"_141":-5,"_39":40,"_38":225,"_143":47,"_36":226,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_26":227},{"_41":216,"_31":217,"_29":218,"_141":-5,"_39":40,"_38":219,"_143":47,"_36":220,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_26":221},{"_41":209,"_31":210,"_29":211,"_141":-5,"_39":40,"_38":212,"_143":47,"_36":213,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_26":215},{"_41":202,"_31":203,"_29":204,"_141":-5,"_39":40,"_38":205,"_143":24,"_36":206,"_13":60,"_33":20,"_34":207,"_23":24,"_147":-5,"_26":208},{"_41":195,"_31":196,"_29":197,"_141":-5,"_39":40,"_38":198,"_143":47,"_36":199,"_13":60,"_33":20,"_34":200,"_23":24,"_147":-5,"_26":201},{"_41":188,"_31":189,"_29":190,"_141":-5,"_39":40,"_38":191,"_143":24,"_36":192,"_13":185,"_33":20,"_34":193,"_23":24,"_147":-5,"_26":194},{"_41":180,"_31":181,"_29":182,"_141":-5,"_39":40,"_38":183,"_143":24,"_36":184,"_13":185,"_33":20,"_34":186,"_23":24,"_147":-5,"_26":187},{"_41":173,"_31":174,"_29":175,"_141":-5,"_39":40,"_38":176,"_143":47,"_36":177,"_13":60,"_33":145,"_34":178,"_23":24,"_147":-5,"_26":179},{"_41":164,"_31":165,"_29":55,"_141":-5,"_39":40,"_38":166,"_143":24,"_36":167,"_13":168,"_33":169,"_34":170,"_23":24,"_147":171,"_26":172},{"_41":156,"_31":157,"_29":158,"_141":-5,"_39":40,"_38":159,"_143":24,"_36":160,"_13":161,"_33":20,"_34":162,"_23":24,"_147":-5,"_26":163},{"_41":149,"_31":150,"_29":151,"_141":-5,"_39":40,"_38":152,"_143":24,"_36":153,"_13":60,"_33":145,"_34":154,"_23":24,"_147":-5,"_26":155},{"_41":138,"_31":139,"_29":140,"_141":-5,"_39":40,"_38":142,"_143":47,"_36":144,"_13":60,"_33":145,"_34":146,"_23":24,"_147":-5,"_26":148},"93344376-b8f1-11f0-ab7b-0224a6c84d84","utils.ts","93344448-b8f1-11f0-ab7b-0224a6c84d84","parentId",24,"latest",["D",1762200814128],"script","import { sqlite } from \"https://esm.town/v/std/sqlite\";\nimport { encoding_for_model } from \"npm:tiktoken\";\nimport { RateLimit } from \"npm:async-sema@latest\";\n\n// Detect if we're running in Val Town (caching enabled) or locally (caching disabled)\n// valtown env var contains a token string when running in Val Town, undefined/null when local\nexport const IS_VALTOWN = typeof Deno !== \"undefined\" && !!Deno.env.get(\"valtown\");\n\n// Rate limiter: 0.33 requests per second (1 request per 3 seconds) to avoid WAF blocking\n// Slower rate to avoid console.groq.com WAF blocking\nexport const fetchRateLimiter = RateLimit(0.33);\n\n// Initialize cache table only in Val Town (bypass SQLite when running locally)\nconst CACHE_TABLE = \"groq_docs_cache_v3\"; // Updated table with hash and embeddings\nif (IS_VALTOWN) {\n try {\n await sqlite.execute(`CREATE TABLE IF NOT EXISTS ${CACHE_TABLE} (\n url TEXT PRIMARY KEY,\n content TEXT NOT NULL,\n charCount INTEGER NOT NULL,\n tokenCount INTEGER,\n frontmatter TEXT NOT NULL,\n metadata TEXT,\n contentHash TEXT,\n embeddings TEXT,\n cachedAt INTEGER NOT NULL\n )`);\n console.log(\"SQLite cache initialized (Val Town)\");\n } catch (error) {\n console.warn(\"Cache table creation failed:\", error instanceof Error ? error.message.substring(0, 100) : String(error).substring(0, 100));\n }\n} else {\n console.log(\"Running locally - SQLite caching disabled\");\n}\n\n// Calculate hash of content for change detection\nexport const calculateContentHash = async (content: string): Promise => {\n // Use Web Crypto API for SHA-256 hashing\n const encoder = new TextEncoder();\n const data = encoder.encode(content);\n const hashBuffer = await crypto.subtle.digest(\"SHA-256\", data);\n const hashArray = Array.from(new Uint8Array(hashBuffer));\n const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');\n return hashHex;\n};\n\n// Debug: Log environment detection\nif (typeof Deno !== \"undefined\") {\n const valtownToken = Deno.env.get(\"valtown\");\n console.log(`Environment detection: IS_VALTOWN=${IS_VALTOWN}, valtown token exists: ${!!valtownToken}`);\n}\n\n// Cache helper functions (bypass SQLite when running locally)\nexport const getFromCache = async (url: string): Promise<{\n content: string;\n charCount: number;\n tokenCount: number | null;\n frontmatter: any;\n metadata: any | null;\n contentHash: string | null;\n embeddings: number[] | null;\n} | null> => {\n if (!IS_VALTOWN) {\n return null; // Skip cache when running locally\n }\n \n try {\n const result = await sqlite.execute({\n sql: `SELECT content, charCount, tokenCount, frontmatter, metadata, contentHash, embeddings FROM ${CACHE_TABLE} WHERE url = ?`,\n args: [url]\n });\n if (result && result.rows && result.rows.length > 0) {\n // Convert row array to object using column names\n const row = result.rows[0];\n const rowObj: any = {};\n result.columns.forEach((col: string, index: number) => {\n rowObj[col] = row[index];\n });\n return {\n content: rowObj.content as string,\n charCount: rowObj.charCount as number,\n tokenCount: rowObj.tokenCount as number | null,\n frontmatter: JSON.parse(rowObj.frontmatter as string),\n metadata: rowObj.metadata ? JSON.parse(rowObj.metadata as string) : null,\n contentHash: rowObj.contentHash as string | null,\n embeddings: rowObj.embeddings ? JSON.parse(rowObj.embeddings as string) : null,\n };\n }\n } catch (error) {\n // Silently fail - caching unavailable\n const errorMessage = error instanceof Error ? error.message : String(error);\n const shortError = errorMessage.length > 200 ? errorMessage.substring(0, 200) + '...' : errorMessage;\n console.debug(\"Cache read failed:\", shortError);\n }\n return null;\n};\n\nexport const setCache = async (url: string, data: { content: string; charCount: number; tokenCount: number | null; frontmatter: any; metadata?: any; contentHash?: string; embeddings?: number[] | null }): Promise => {\n if (!IS_VALTOWN) {\n return \"Cache unavailable - running locally\";\n }\n \n try {\n await sqlite.execute({\n sql: `INSERT OR REPLACE INTO ${CACHE_TABLE} (url, content, charCount, tokenCount, frontmatter, metadata, contentHash, embeddings, cachedAt) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n args: [\n url,\n data.content,\n data.charCount,\n data.tokenCount,\n JSON.stringify(data.frontmatter),\n data.metadata ? JSON.stringify(data.metadata) : null,\n data.contentHash || null,\n data.embeddings ? JSON.stringify(data.embeddings) : null,\n Date.now(),\n ]\n });\n return null; // Success - no error\n } catch (error) {\n // Return error message for tracking\n const errorMessage = error instanceof Error ? error.message : String(error);\n const shortError = errorMessage.length > 200 ? errorMessage.substring(0, 200) + '...' : errorMessage;\n console.debug(\"Cache write failed:\", shortError);\n return shortError;\n }\n};\n\nexport const clearCache = async (url?: string) => {\n if (!IS_VALTOWN) {\n throw new Error(\"Cache unavailable - running locally\");\n }\n \n try {\n if (url) {\n await sqlite.execute({\n sql: `DELETE FROM ${CACHE_TABLE} WHERE url = ?`,\n args: [url]\n });\n } else {\n await sqlite.execute(`DELETE FROM ${CACHE_TABLE}`);\n }\n } catch (error) {\n console.debug(\"Cache clear failed:\", error instanceof Error ? error.message.substring(0, 100) : String(error).substring(0, 100));\n throw error; // Re-throw for endpoints that need to know if it failed\n }\n};\n\nexport const getCacheStats = async () => {\n if (!IS_VALTOWN) {\n return {\n cachedPages: 0,\n totalTokens: 0,\n message: \"Cache unavailable - running locally\",\n };\n }\n \n try {\n const result = await sqlite.execute(`SELECT COUNT(*) as count, SUM(tokenCount) as totalTokens FROM ${CACHE_TABLE}`);\n if (result && result.rows && result.rows.length > 0) {\n const row = result.rows[0];\n const rowObj: any = {};\n result.columns.forEach((col: string, index: number) => {\n rowObj[col] = row[index];\n });\n return {\n cachedPages: rowObj.count || 0,\n totalTokens: rowObj.totalTokens || 0,\n };\n }\n return {\n cachedPages: 0,\n totalTokens: 0,\n };\n } catch (error) {\n console.debug(\"Cache stats failed:\", error instanceof Error ? error.message.substring(0, 100) : String(error).substring(0, 100));\n return {\n cachedPages: 0,\n totalTokens: 0,\n };\n }\n};\n\nexport const getTextFromUrl = async (url: string) => {\n // Use rate limiter to avoid WAF blocking\n await fetchRateLimiter();\n \n const response = await fetch(url, {\n headers: {\n \"User-Agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36\",\n \"Accept\": \"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\",\n }\n });\n \n if (!response.ok) {\n throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n }\n \n const text = await response.text();\n return text;\n};\n\nexport const parseFrontmatter = (text: string) => {\n const frontmatterRegex = /^---\\s*\\n([\\s\\S]*?)\\n---\\s*\\n?/;\n const match = text.match(frontmatterRegex);\n \n if (!match) {\n return {};\n }\n \n const frontmatterText = match[1];\n const metadata: any = {};\n \n // Parse YAML-like frontmatter (simple key: value parsing)\n const lines = frontmatterText.split('\\n');\n for (const line of lines) {\n const colonIndex = line.indexOf(':');\n if (colonIndex > 0) {\n const key = line.substring(0, colonIndex).trim();\n const value = line.substring(colonIndex + 1).trim();\n // Remove quotes if present\n metadata[key] = value.replace(/^[\"']|[\"']$/g, '');\n }\n }\n \n return metadata;\n};\n\nexport const addUrlSourceToFrontmatter = (text: string, url: string) => {\n // Check if frontmatter exists\n const frontmatterRegex = /^---\\s*\\n([\\s\\S]*?)\\n---\\s*\\n?/;\n const match = text.match(frontmatterRegex);\n \n if (match) {\n // Frontmatter exists, add urlSource to it\n const existingFrontmatter = match[1];\n \n // Check if urlSource already exists\n if (existingFrontmatter.includes('urlSource:')) {\n // Replace existing urlSource\n const updatedFrontmatter = existingFrontmatter.replace(\n /urlSource:\\s*.+$/m,\n `urlSource: ${url}`\n );\n return text.replace(frontmatterRegex, `---\\n${updatedFrontmatter}\\n---\\n`);\n } else {\n // Add urlSource at the end of frontmatter\n const updatedFrontmatter = existingFrontmatter.trim() + `\\nurlSource: ${url}`;\n return text.replace(frontmatterRegex, `---\\n${updatedFrontmatter}\\n---\\n\\n`);\n }\n } else {\n // No frontmatter exists, add it\n return `---\nurlSource: ${url}\n---\n\n${text}`;\n }\n};\n\nexport const calculateTokenCount = (text: string): number => {\n try {\n // Use cl100k_base encoding (used by GPT-4 and many models)\n const encoding = encoding_for_model(\"gpt-4\");\n return encoding.encode(text).length;\n } catch (error) {\n console.error(\"Error calculating token count:\", error);\n return 0;\n }\n};\n\n","label",[139],"3178e154-b901-11f0-87ce-0224a6c84d84","urls.ts","3178e244-b901-11f0-87ce-0224a6c84d84",36,["D",1762207522123],"export\n const urls = [\n \"https://console.groq.com/docs.md\",\n \"https://console.groq.com/docs/agentic-tooling.md\",\n \"https://console.groq.com/docs/agentic-tooling/compound-beta.md\",\n \"https://console.groq.com/docs/agentic-tooling/compound-beta-mini.md\",\n \"https://console.groq.com/docs/agno.md\",\n \"https://console.groq.com/docs/ai-sdk.md\",\n \"https://console.groq.com/docs/anchorbrowser.md\",\n // \"https://console.groq.com/docs/api-reference.md\",\n // \"https://console.groq.com/docs/arize.md\",\n // \"https://console.groq.com/docs/autogen.md\",\n // \"https://console.groq.com/docs/badge.md\",\n // \"https://console.groq.com/docs/batch.md\",\n // \"https://console.groq.com/docs/billing-faqs.md\",\n // \"https://console.groq.com/docs/browser-automation.md\",\n // \"https://console.groq.com/docs/browser-search.md\",\n // \"https://console.groq.com/docs/browserbase.md\",\n // \"https://console.groq.com/docs/browseruse.md\",\n // \"https://console.groq.com/docs/changelog.md\",\n // \"https://console.groq.com/docs/changelog/compound.md\",\n // \"https://console.groq.com/docs/code-execution.md\",\n // \"https://console.groq.com/docs/composio.md\",\n // \"https://console.groq.com/docs/compound.md\",\n // \"https://console.groq.com/docs/compound/built-in-tools.md\",\n // \"https://console.groq.com/docs/compound/systems.md\",\n // \"https://console.groq.com/docs/compound/systems/compound.md\",\n // \"https://console.groq.com/docs/compound/systems/compound-beta.md\",\n // \"https://console.groq.com/docs/compound/systems/compound-beta-mini.md\",\n // \"https://console.groq.com/docs/compound/systems/compound-mini.md\",\n // \"https://console.groq.com/docs/compound/use-cases.md\",\n // \"https://console.groq.com/docs/content-moderation.md\",\n // \"https://console.groq.com/docs/crewai.md\",\n // \"https://console.groq.com/docs/deprecations.md\",\n // \"https://console.groq.com/docs/e2b.md\",\n // \"https://console.groq.com/docs/errors.md\",\n // \"https://console.groq.com/docs/exa.md\",\n // \"https://console.groq.com/docs/examples.md\",\n // \"https://console.groq.com/docs/firecrawl.md\",\n // \"https://console.groq.com/docs/flex-processing.md\",\n // \"https://console.groq.com/docs/flutterflow.md\",\n // \"https://console.groq.com/docs/gradio.md\",\n // \"https://console.groq.com/docs/guides/speech-to-text/prompting.md\",\n // \"https://console.groq.com/docs/huggingface.md\",\n // \"https://console.groq.com/docs/integrations.md\",\n // \"https://console.groq.com/docs/jigsawstack.md\",\n // \"https://console.groq.com/docs/langchain.md\",\n // \"https://console.groq.com/docs/legacy-changelog.md\",\n // \"https://console.groq.com/docs/legal.md\",\n // \"https://console.groq.com/docs/legal/ai-policy.md\",\n // \"https://console.groq.com/docs/legal/services-agreement.md\",\n // \"https://console.groq.com/docs/libraries.md\",\n // \"https://console.groq.com/docs/litellm.md\",\n // \"https://console.groq.com/docs/livekit.md\",\n // \"https://console.groq.com/docs/llama-index.md\",\n // \"https://console.groq.com/docs/lora.md\",\n // \"https://console.groq.com/docs/mastra.md\",\n // \"https://console.groq.com/docs/mcp.md\",\n // \"https://console.groq.com/docs/mlflow.md\",\n // \"https://console.groq.com/docs/model-permissions.md\",\n // \"https://console.groq.com/docs/model/llama-3.1-8b-instant.md\",\n // \"https://console.groq.com/docs/model/llama-3.3-70b-versatile.md\",\n // \"https://console.groq.com/docs/model/llama-4-maverick-17b-128e-instruct.md\",\n // \"https://console.groq.com/docs/model/llama-4-scout-17b-16e-instruct.md\",\n // \"https://console.groq.com/docs/model/llama-guard-4-12b.md\",\n // \"https://console.groq.com/docs/model/llama-prompt-guard-2-22m.md\",\n // \"https://console.groq.com/docs/model/llama-prompt-guard-2-86m.md\",\n // \"https://console.groq.com/docs/model/meta-llama/llama-4-maverick-17b-128e-instruct.md\",\n // \"https://console.groq.com/docs/model/meta-llama/llama-4-scout-17b-16e-instruct.md\",\n // \"https://console.groq.com/docs/model/meta-llama/llama-guard-4-12b.md\",\n // \"https://console.groq.com/docs/model/meta-llama/llama-prompt-guard-2-22m.md\",\n // \"https://console.groq.com/docs/model/meta-llama/llama-prompt-guard-2-86m.md\",\n // \"https://console.groq.com/docs/model/moonshotai/kimi-k2-instruct.md\",\n // \"https://console.groq.com/docs/model/moonshotai/kimi-k2-instruct-0905.md\",\n // \"https://console.groq.com/docs/model/openai/gpt-oss-120b.md\",\n // \"https://console.groq.com/docs/model/openai/gpt-oss-20b.md\",\n // \"https://console.groq.com/docs/model/openai/gpt-oss-safeguard-20b.md\",\n // \"https://console.groq.com/docs/model/playai-tts.md\",\n // \"https://console.groq.com/docs/model/playai-tts-arabic.md\",\n // \"https://console.groq.com/docs/model/qwen/qwen3-32b.md\",\n // \"https://console.groq.com/docs/model/qwen3-32b.md\",\n // \"https://console.groq.com/docs/model/whisper-large-v3.md\",\n // \"https://console.groq.com/docs/model/whisper-large-v3-turbo.md\",\n // \"https://console.groq.com/docs/models.md\",\n // \"https://console.groq.com/docs/openai.md\",\n // \"https://console.groq.com/docs/overview.md\",\n // \"https://console.groq.com/docs/parallel.md\",\n // \"https://console.groq.com/docs/prefilling.md\",\n // \"https://console.groq.com/docs/production-readiness/optimizing-latency.md\",\n // \"https://console.groq.com/docs/production-readiness/production-ready-checklist.md\",\n // \"https://console.groq.com/docs/production-readiness/security-onboarding.md\",\n // \"https://console.groq.com/docs/projects.md\",\n // \"https://console.groq.com/docs/prompt-caching.md\",\n // \"https://console.groq.com/docs/prompting.md\",\n // \"https://console.groq.com/docs/prompting/model-migration.md\",\n // \"https://console.groq.com/docs/prompting/patterns.md\",\n // \"https://console.groq.com/docs/quickstart.md\",\n // \"https://console.groq.com/docs/rate-limits.md\",\n // \"https://console.groq.com/docs/reasoning.md\",\n // \"https://console.groq.com/docs/responses-api.md\",\n // \"https://console.groq.com/docs/speech-text.md\",\n // \"https://console.groq.com/docs/speech-to-text.md\",\n // \"https://console.groq.com/docs/spend-limits.md\",\n // \"https://console.groq.com/docs/structured-outputs.md\",\n // \"https://console.groq.com/docs/tavily.md\",\n // \"https://console.groq.com/docs/text-chat.md\",\n // \"https://console.groq.com/docs/text-to-speech.md\",\n // \"https://console.groq.com/docs/tool-use.md\",\n // \"https://console.groq.com/docs/toolhouse.md\",\n // \"https://console.groq.com/docs/vision.md\",\n // \"https://console.groq.com/docs/web-search.md\",\n // \"https://console.groq.com/docs/wolfram-alpha.md\",\n // \"https://console.groq.com/docs/xrx.md\",\n // \"https://console.groq.com/docs/your-data.md\",\n ];\n",[150],"31eadcc8-b901-11f0-9996-0224a6c84d84","todo.md","7ebe7d74-b8ee-11f0-bdd9-0224a6c84d84",47,["D",1762207522872],1,"\n## todos\n- [ ] markdown endpoint\n- [ ] pre-calculate metadata around each markdown page\n- [ ] pre-calculate complex question query q&a pairs that map to various pages and categories\n\n\n## future\n- [ ] (Ben) can we have a blind eval ranker - aka we show the two results side by side and you pick A or B and do this like 20 times, then it shows you which one ranked better",[157],"31b07fce-b901-11f0-85e4-0224a6c84d84","main.tsx",42,["D",1762207522732],14,"http","import { Hono } from \"https://deno.land/x/hono@v3.11.7/mod.ts\";\nimport \"jsr:@std/dotenv/load\";\nimport {\n IS_VALTOWN,\n getFromCache,\n setCache,\n clearCache,\n getCacheStats,\n getTextFromUrl,\n parseFrontmatter,\n addUrlSourceToFrontmatter,\n calculateTokenCount,\n calculateContentHash,\n} from \"./utils.ts\";\nimport { generatePageMetadata } from \"./groq.ts\";\nimport { searchPages, getActiveEmbeddingsFunction, type Page } from \"./search/index.ts\";\nimport { urls } from \"./urls.ts\";\n\nconst app = new Hono();\n\n\n\n\n\n\nconst getPageContent = async () => {\n const promises = urls.map(async url => {\n const text = await getTextFromUrl(url);\n return addUrlSourceToFrontmatter(text, url);\n });\n const texts = await Promise.all(promises);\n return texts.join(\"\\n\\n\");\n};\n\nconst getPageData = async () => {\n const pageData = await Promise.all(\n urls.map(async (url) => {\n // Check if cached\n const cached = await getFromCache(url);\n let text, processedText, charCount, frontmatter, wasCached;\n \n let metadata = null;\n \n if (cached) {\n // Use cached data\n text = cached.content;\n processedText = cached.content;\n charCount = cached.charCount;\n frontmatter = cached.frontmatter;\n metadata = cached.metadata;\n wasCached = true;\n } else {\n // Fetch fresh\n text = await getTextFromUrl(url);\n processedText = addUrlSourceToFrontmatter(text, url);\n charCount = processedText.length;\n frontmatter = parseFrontmatter(processedText);\n wasCached = false;\n }\n \n // Extract urlSource and rename it to url, then flatten remaining frontmatter properties\n const urlSource = (frontmatter as any).urlSource;\n const restFrontmatter = { ...frontmatter };\n delete (restFrontmatter as any).urlSource;\n \n return {\n url: urlSource || url, // Use urlSource from frontmatter, fallback to url\n content: processedText,\n charCount,\n cached: wasCached,\n ...restFrontmatter, // Flatten frontmatter properties\n ...(metadata || {}), // Include AI-generated metadata if available\n };\n })\n );\n \n return {\n pages: pageData,\n totalPages: pageData.length,\n totalChars: pageData.reduce((sum, { charCount }) => sum + charCount, 0),\n cachedPages: pageData.filter(({ cached }) => cached).length,\n };\n};\n\napp.get(\"/\", async (c) => {\n const content = await getPageContent();\n return c.text(content);\n});\n\napp.get(\"/data\", async (c) => {\n const data = await getPageData();\n \n // Extract page paths/names (same logic as /list endpoint)\n const pagePaths = urls.map(url => {\n const match = url.match(/\\/docs\\/(.+?)\\.md$/);\n if (match) {\n return match[1];\n }\n if (url.endsWith(\"/docs.md\")) {\n return \"docs\";\n }\n return null;\n }).filter(path => path !== null);\n \n // Return metadata first, then the large data object\n return c.json({\n metadata: {\n urls: pagePaths,\n },\n ...data,\n });\n});\n\napp.get(\"/list\", async (c) => {\n const paths = urls.map(url => {\n // Extract the path part after /docs/ and remove .md extension\n const match = url.match(/\\/docs\\/(.+?)\\.md$/);\n if (match) {\n return match[1];\n }\n // Handle the case where URL is just /docs.md - return \"docs\"\n if (url.endsWith(\"/docs.md\")) {\n return \"docs\";\n }\n return null;\n }).filter(path => path !== null);\n \n return c.json(paths);\n});\n\n// Helper function to load data from latest.json (for local development)\nasync function loadLatestJsonForSearch(): Promise | null> {\n if (IS_VALTOWN) {\n return null; // Use SQLite when in Val Town\n }\n \n try {\n const latestData = await Deno.readTextFile(\"./data/latest.json\");\n const data = JSON.parse(latestData);\n \n const cacheMap: Record = {};\n \n if (data.results && Array.isArray(data.results)) {\n for (const result of data.results) {\n if (result.url && !result.skipped && !result.error) {\n cacheMap[result.url] = {\n title: result.title,\n embeddings: result.embeddings || null,\n metadata: result.metadata || null,\n };\n }\n }\n }\n \n return cacheMap;\n } catch {\n return null;\n }\n}\n\n// Helper function to get all pages for searching\nexport const getAllPagesForSearch = async (): Promise => {\n // Load JSON cache when running locally\n const jsonCache = await loadLatestJsonForSearch();\n \n const pageData: (Page | null)[] = await Promise.all(\n urls.map(async (url): Promise => {\n // Extract path from URL\n const match = url.match(/\\/docs\\/(.+?)\\.md$/);\n const path = match ? match[1] : (url.endsWith(\"/docs.md\") ? \"docs\" : null);\n \n if (!path) {\n return null;\n }\n \n // Try to get from SQLite cache first\n const cached = await getFromCache(url);\n \n if (cached) {\n const frontmatter = cached.frontmatter;\n return {\n path,\n url: cached.frontmatter?.urlSource || url,\n content: cached.content,\n title: frontmatter?.title || path,\n embeddings: cached.embeddings,\n metadata: cached.metadata,\n };\n }\n \n // If not in SQLite, try JSON cache (when running locally)\n if (jsonCache && jsonCache[url]) {\n const jsonData = jsonCache[url];\n // We still need content for search, so fetch it\n // But use cached embeddings and metadata\n try {\n const pageData = await getPageByPath(path, false);\n if (pageData) {\n const frontmatter = parseFrontmatter(pageData.content);\n return {\n path,\n url: pageData.url,\n content: pageData.content,\n title: jsonData.title || frontmatter?.title || path,\n embeddings: jsonData.embeddings || null,\n metadata: jsonData.metadata || null,\n };\n }\n } catch (error) {\n // If fetch fails, skip this page\n return null;\n }\n }\n \n // If not cached anywhere, fetch it (but don't cache during search to avoid slowing down)\n try {\n const pageData = await getPageByPath(path, false);\n if (pageData) {\n const frontmatter = parseFrontmatter(pageData.content);\n return {\n path,\n url: pageData.url,\n content: pageData.content,\n title: frontmatter?.title,\n embeddings: null,\n metadata: null,\n };\n }\n } catch (error) {\n // Skip pages that fail to fetch\n return null;\n }\n \n return null;\n })\n );\n \n // Filter out nulls\n return pageData.filter((p): p is Page => p !== null);\n};\n\n// Search endpoint - uses active strategy from search/index.ts\napp.get(\"/search\", async (c) => {\n const query = c.req.query(\"q\");\n const limit = parseInt(c.req.query(\"limit\") || \"10\");\n const minScore = parseFloat(c.req.query(\"minScore\") || \"0\");\n \n if (!query) {\n return c.json({ error: \"Query parameter 'q' is required\" }, 400);\n }\n \n const validPages = await getAllPagesForSearch();\n \n // Perform search using active strategy\n const results = await searchPages(query, validPages, {\n limit,\n minScore,\n });\n \n return c.json({\n query,\n results,\n totalResults: results.length,\n totalPages: validPages.length,\n });\n});\n\n// Test search endpoint - runs test queries against active search strategy\napp.get(\"/search/test\", async (c) => {\n try {\n // Import test utilities and get active strategy info\n const { runSearchTest } = await import(\"./testing/search-harness.ts\");\n const { questions } = await import(\"./testing/questions.ts\");\n const { searchStrategy } = await import(\"./search/index.ts\");\n \n const validPages = await getAllPagesForSearch();\n const testQueries = questions;\n \n const testResults: Array<{\n query: string;\n results: Array<{\n path: string;\n url: string;\n title?: string;\n score: number;\n snippet: string;\n metadata?: {\n strategy?: string;\n [key: string]: any;\n };\n }>;\n durationMs: number;\n resultCount: number;\n error?: string;\n }> = [];\n \n for (const query of testQueries) {\n const testResult = await runSearchTest(query, validPages, {\n limit: 10,\n minScore: 0,\n enableTiming: true,\n });\n \n testResults.push({\n query,\n results: testResult.results.map(r => ({\n path: r.path,\n url: r.url,\n title: r.title,\n score: r.score,\n snippet: r.snippet?.substring(0, 200) || '', // Limit snippet length\n metadata: r.metadata,\n })),\n durationMs: testResult.durationMs,\n resultCount: testResult.results.length,\n error: testResult.error || undefined,\n });\n }\n \n return c.json({\n strategy: {\n name: searchStrategy.name,\n description: searchStrategy.description,\n },\n totalQueries: testQueries.length,\n totalPages: validPages.length,\n tests: testResults,\n summary: {\n totalDurationMs: testResults.reduce((sum, t) => sum + t.durationMs, 0),\n avgDurationMs: testResults.reduce((sum, t) => sum + t.durationMs, 0) / testResults.length,\n totalResults: testResults.reduce((sum, t) => sum + t.resultCount, 0),\n errors: testResults.filter(t => t.error).length,\n },\n });\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n return c.json({ \n error: \"Test search failed\", \n message: errorMessage \n }, 500);\n }\n});\n\n\nconst getPageByPath = async (pathParam: string, useCache: boolean = true) => {\n // Find the matching URL\n const matchingUrl = urls.find(url => {\n // Extract the path part after /docs/ and remove .md extension\n const match = url.match(/\\/docs\\/(.+?)\\.md$/);\n if (match) {\n return match[1] === pathParam;\n }\n // Handle the case where URL is just /docs.md and pathParam is \"docs\"\n if (url.endsWith(\"/docs.md\") && pathParam === \"docs\") {\n return true;\n }\n return false;\n });\n \n if (!matchingUrl) {\n return null;\n }\n \n // Try to get from cache first\n if (useCache) {\n const cached = await getFromCache(matchingUrl);\n if (cached) {\n // Extract urlSource and rename it to url, then flatten remaining frontmatter properties\n const urlSource = (cached.frontmatter as any).urlSource;\n const restFrontmatter = { ...cached.frontmatter };\n delete (restFrontmatter as any).urlSource;\n \n return {\n url: urlSource || matchingUrl,\n content: cached.content,\n charCount: cached.charCount,\n tokenCount: cached.tokenCount,\n cached: true,\n ...restFrontmatter,\n ...(cached.metadata || {}), // Include AI-generated metadata if available\n };\n }\n }\n \n // Fetch and process the single page\n const text = await getTextFromUrl(matchingUrl);\n const processedText = addUrlSourceToFrontmatter(text, matchingUrl);\n const charCount = processedText.length;\n const tokenCount = calculateTokenCount(processedText);\n const frontmatter = parseFrontmatter(processedText);\n \n // Cache the result (without metadata for now - generated during recalculate)\n if (useCache) {\n // Wrap in additional error handling to ensure it never throws\n try {\n await setCache(matchingUrl, {\n content: processedText,\n charCount,\n tokenCount,\n frontmatter,\n });\n } catch (error) {\n // Double safety - setCache should already catch, but just in case\n console.debug(\"Cache write error (ignored):\", error instanceof Error ? error.message.substring(0, 100) : String(error).substring(0, 100));\n }\n }\n \n // Extract urlSource and rename it to url, then flatten remaining frontmatter properties\n const urlSource = (frontmatter as any).urlSource;\n const restFrontmatter = { ...frontmatter };\n delete (restFrontmatter as any).urlSource;\n \n return {\n url: urlSource || matchingUrl, // Use urlSource from frontmatter, fallback to matchingUrl\n content: processedText,\n charCount,\n tokenCount,\n cached: false,\n ...restFrontmatter,\n };\n};\n\napp.get(\"/page/docs\", async (c) => {\n // Handle root docs case\n const pageData = await getPageByPath(\"docs\");\n if (!pageData) {\n return c.json({ error: \"Page not found\" }, 404);\n }\n return c.json(pageData);\n});\n\napp.get(\"/page/*\", async (c) => {\n // Get the path from the URL (everything after /page/)\n const urlPath = new URL(c.req.url).pathname;\n const pathParam = urlPath.replace(\"/page/\", \"\") || \"\";\n \n const pageData = await getPageByPath(pathParam);\n if (!pageData) {\n return c.json({ error: \"Page not found\" }, 404);\n }\n return c.json(pageData);\n});\n\n// Cache management endpoints (all GET for browser access)\napp.get(\"/cache/stats\", async (c) => {\n const stats = await getCacheStats();\n return c.json(stats);\n});\n\napp.get(\"/cache/clear\", async (c) => {\n try {\n await clearCache();\n return c.json({ message: \"Cache cleared\", success: true });\n } catch (error) {\n return c.json({ \n message: \"Cache unavailable (caching disabled)\", \n success: false,\n error: \"SQLite not available - caching disabled\" \n });\n }\n});\n\napp.get(\"/cache/clear/:path\", async (c) => {\n const pathParam = c.req.param(\"path\");\n \n // Find the matching URL\n const matchingUrl = urls.find(url => {\n const match = url.match(/\\/docs\\/(.+?)\\.md$/);\n if (match) {\n return match[1] === pathParam;\n }\n if (url.endsWith(\"/docs.md\") && pathParam === \"docs\") {\n return true;\n }\n return false;\n });\n \n if (!matchingUrl) {\n return c.json({ error: \"Page not found\" }, 404);\n }\n \n try {\n await clearCache(matchingUrl);\n return c.json({ message: `Cache cleared for ${pathParam}`, success: true });\n } catch (error) {\n return c.json({ \n message: `Cache unavailable for ${pathParam} (caching disabled)`, \n success: false,\n error: \"SQLite not available - caching disabled\" \n });\n }\n});\n\napp.get(\"/cache/recalculate\", async (c) => {\n // Check for force mode (bypass hash checking)\n const force = c.req.query(\"force\") === \"true\";\n \n // Recalculate all pages (bypass cache) with AI metadata generation\n const results: Array<{ \n path: string; \n url: string; \n charCount: number; \n tokenCount: number | undefined;\n title?: string;\n metadata?: any;\n error?: string;\n cacheError?: string;\n skipped?: boolean;\n reason?: string;\n }> = [];\n \n let processedCount = 0;\n let skippedCount = 0;\n \n for (const url of urls) {\n // Extract path from URL\n const match = url.match(/\\/docs\\/(.+?)\\.md$/);\n const path = match ? match[1] : (url.endsWith(\"/docs.md\") ? \"docs\" : null);\n \n if (path) {\n console.log(`[${processedCount + 1}/${urls.length}] Processing ${path}...`);\n \n try {\n // Check cached hash if not forcing\n let shouldSkip = false;\n if (!force) {\n const cached = await getFromCache(url);\n if (cached && cached.contentHash) {\n // Fetch fresh content to check hash\n try {\n const pageData = await getPageByPath(path, false);\n if (pageData) {\n const newHash = await calculateContentHash(pageData.content);\n if (newHash === cached.contentHash) {\n shouldSkip = true;\n skippedCount++;\n console.log(` Skipped ${path} (content unchanged, hash: ${newHash.substring(0, 8)}...)`);\n results.push({\n path,\n url,\n charCount: cached.charCount,\n tokenCount: cached.tokenCount || undefined,\n title: (cached.frontmatter as any).title || path,\n metadata: cached.metadata || undefined,\n skipped: true,\n reason: \"Content unchanged (hash matches)\",\n });\n }\n }\n } catch (hashCheckError) {\n // If hash check fails, continue with processing\n console.debug(` Hash check failed for ${path}, continuing...`);\n }\n }\n }\n \n if (shouldSkip) {\n processedCount++;\n continue;\n }\n \n // Fetch without cache (rate limiting handled by async-sema)\n let pageData;\n try {\n pageData = await getPageByPath(path, false);\n } catch (fetchError) {\n const fetchErrorMessage = fetchError instanceof Error ? fetchError.message : String(fetchError);\n console.error(` Failed to fetch ${path}:`, fetchErrorMessage);\n throw new Error(`Fetch failed: ${fetchErrorMessage}`);\n }\n \n if (pageData) {\n const frontmatter = parseFrontmatter(pageData.content);\n const title = (frontmatter as any).title || path;\n \n // Calculate content hash\n const contentHash = await calculateContentHash(pageData.content);\n \n // Generate AI metadata (failures are handled inside generatePageMetadata)\n const metadata = await generatePageMetadata(pageData.content, title);\n if (!metadata) {\n console.warn(` Metadata generation failed for ${path} (continuing without metadata)`);\n }\n \n // Generate embeddings using active strategy's embeddings function\n const generateEmbeddings = getActiveEmbeddingsFunction();\n const embeddings = await generateEmbeddings(pageData.content);\n \n // Cache it with metadata, hash, and embeddings - track errors\n const cacheError = await setCache(url, {\n content: pageData.content,\n charCount: pageData.charCount,\n tokenCount: pageData.tokenCount || null,\n frontmatter,\n metadata,\n contentHash,\n embeddings,\n });\n \n results.push({ \n path, \n url, \n charCount: pageData.charCount, \n tokenCount: pageData.tokenCount,\n title,\n metadata, // Include full metadata in results\n ...(cacheError && { cacheError }), // Include cache error if present\n });\n \n if (cacheError) {\n console.warn(`Completed ${path} (metadata: ${metadata ? 'yes' : 'no'}, embeddings: ${embeddings ? 'yes' : 'no'}, cache error: ${cacheError})`);\n } else {\n console.log(`Completed ${path} (metadata: ${metadata ? 'yes' : 'no'}, embeddings: ${embeddings ? 'yes' : 'no'}, cached: yes)`);\n }\n }\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n console.error(`Error processing ${path}:`, errorMessage);\n results.push({\n path,\n url,\n charCount: 0,\n tokenCount: 0,\n error: errorMessage,\n });\n }\n \n processedCount++;\n }\n }\n \n const cacheErrors = results.filter(r => r.cacheError);\n const processedResults = results.filter(r => !r.skipped);\n \n return c.json({\n message: force \n ? `Recalculated ${processedResults.length} pages with AI metadata (force mode)` \n : `Recalculated ${processedResults.length} pages, skipped ${skippedCount} unchanged pages`,\n results, // Now includes full metadata for each page\n totalPages: results.length,\n processed: processedResults.length,\n skipped: skippedCount,\n withMetadata: processedResults.filter(r => r.metadata).length,\n withoutMetadata: processedResults.filter(r => !r.metadata).length,\n cached: processedResults.length > 0 && cacheErrors.length === 0, // True if all pages cached successfully\n cacheErrors: cacheErrors.length > 0 ? cacheErrors.map(r => ({ path: r.path, error: r.cacheError })) : undefined,\n force,\n });\n});\n\n// Helper function to save test data to /data/mm-dd-yyyy.json and /data/latest.json\nexport const saveTestData = async (data: any, customDate?: Date) => {\n const date = customDate || new Date();\n const month = String(date.getMonth() + 1).padStart(2, '0');\n const day = String(date.getDate()).padStart(2, '0');\n const year = date.getFullYear();\n const filename = `${month}-${day}-${year}.json`;\n const datedFilepath = `./data/${filename}`;\n const latestFilepath = `./data/latest.json`;\n \n try {\n // Ensure data directory exists\n try {\n await Deno.mkdir(\"./data\", { recursive: true });\n } catch {\n // Directory already exists, ignore\n }\n \n const jsonData = JSON.stringify(data, null, 2);\n \n // Write both files\n await Deno.writeTextFile(datedFilepath, jsonData);\n await Deno.writeTextFile(latestFilepath, jsonData);\n \n console.log(`Data saved to ${datedFilepath} and ${latestFilepath}`);\n return { datedFilepath, latestFilepath };\n } catch (error) {\n console.error(`Failed to save test data:`, error);\n throw error;\n }\n};\n\nexport default (typeof Deno !== \"undefined\" && Deno.env.get(\"valtown\")) ? app.fetch : app;\n","groqdocs",[165],"9315b67c-b8f1-11f0-85fe-0224a6c84d84","groq.ts","9315b744-b8f1-11f0-85fe-0224a6c84d84",23,["D",1762200814266],"import { RateLimit } from \"npm:async-sema@latest\";\n\n// Groq API Configuration\nconst GROQ_API_KEY = Deno.env.get(\"GROQ_API_KEY\");\nconst GROQ_API_URL = \"https://api.groq.com/openai/v1/chat/completions\";\n\n// Rate limiter for Groq API: 2 requests per second to avoid rate limits\nconst groqApiRateLimiter = RateLimit(2);\n\n// Groq Chat Completions Utility\nexport const groqChatCompletion = async (messages: Array<{ role: string; content: string }>, options: {\n model?: string;\n temperature?: number;\n max_tokens?: number;\n response_format?: { type: string };\n} = {}) => {\n if (!GROQ_API_KEY) {\n console.warn(\"GROQ_API_KEY not found - AI metadata generation disabled\");\n return null;\n }\n\n // Rate limit Groq API calls\n await groqApiRateLimiter();\n\n try {\n const response = await fetch(GROQ_API_URL, {\n method: \"POST\",\n headers: {\n \"Authorization\": `Bearer ${GROQ_API_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n model: options.model || \"llama-3.3-70b-versatile\",\n messages,\n temperature: options.temperature ?? 0.4,\n // max_tokens: options.max_tokens ?? 1024,\n ...(options.response_format && { response_format: options.response_format }),\n }),\n });\n\n if (!response.ok) {\n const errorText = await response.text().catch(() => response.statusText);\n throw new Error(`Groq API error: ${response.status} ${response.statusText} - ${errorText.substring(0, 200)}`);\n }\n\n const data = await response.json();\n return data.choices[0]?.message?.content || null;\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n console.error(\"Groq API call failed:\", errorMessage);\n // Don't throw - return null so metadata generation doesn't break the whole process\n return null;\n }\n};\n\n// Generate AI metadata for a page\nexport const generatePageMetadata = async (content: string, title: string) => {\n const prompt = `Analyze this documentation page and provide metadata in JSON format.\n\nPage Title: ${title}\n\nContent:\n${content.substring(0, 4000)} ${content.length > 4000 ? '...(truncated)' : ''}\n\nGenerate the following metadata:\n1. categories: Array of 2-4 broad categories (e.g., \"API\", \"Authentication\", \"Models\", \"Integration\")\n2. tags: Array of 5-10 specific tags/keywords\n3. useCases: Array of 2-4 practical use cases or scenarios when this page would be helpful\n4. questions: Array of 5-10 questions users might ask that this page answers\n\nReturn ONLY valid JSON in this exact format:\n{\n \"categories\": [\"Category1\", \"Category2\"],\n \"tags\": [\"tag1\", \"tag2\", \"tag3\"],\n \"useCases\": [\"Use case 1\", \"Use case 2\"],\n \"questions\": [\"Question 1?\", \"Question 2?\"]\n}`;\n\n const response = await groqChatCompletion([\n { role: \"user\", content: prompt }\n ], {\n model: \"llama-3.3-70b-versatile\",\n temperature: 0.3,\n max_tokens: 1024,\n });\n\n if (!response) {\n return null;\n }\n\n try {\n // Extract JSON from response (in case it's wrapped in markdown)\n const jsonMatch = response.match(/\\{[\\s\\S]*\\}/);\n if (jsonMatch) {\n return JSON.parse(jsonMatch[0]);\n }\n return JSON.parse(response);\n } catch (error) {\n console.error(\"Failed to parse AI metadata:\", error);\n return null;\n }\n};\n\n",[174],"31bd3a34-b901-11f0-a8ca-0224a6c84d84","deno.json","656e5404-b8e7-11f0-a061-0224a6c84d84",44,["D",1762207522854],2,"{\n \"tasks\": {\n \"serve\": \"deno serve --allow-net --allow-import --allow-read --allow-write --allow-env main.tsx\",\n \"recalculate\": \"deno run --allow-net --allow-import --allow-read --allow-write --allow-env testing/recalculate.ts\",\n \"recalculate-force\": \"deno run --allow-net --allow-import --allow-read --allow-write --allow-env testing/recalculate.ts --force\",\n \"test:search\": \"deno run --allow-net --allow-import --allow-read --allow-write --allow-env testing/test-search.ts\"\n },\n \"$schema\": \"https://raw.githubusercontent.com/denoland/deno/98f62cee78e85bfc47c62ed703777c6bc8794f1c/cli/schemas/config-file.v1.json\",\n \"lock\": false,\n \"compilerOptions\": {\n \"noImplicitAny\": false,\n \"strict\": true,\n \"types\": [\"https://www.val.town/types/valtown.d.ts\"],\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ]\n },\n \"lint\": {\n \"include\": [\"deno:/https/esm.town/**/*\"],\n \"rules\": {\n \"exclude\": [\"no-explicit-any\"]\n }\n },\n \"node_modules_dir\": false,\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true,\n \"unstable-sloppy-imports\": true\n }\n}",[181],"936414fc-b8f1-11f0-92bd-0224a6c84d84","README.md","6566e58e-b8e7-11f0-9e62-0224a6c84d84",25,["D",1762200814124],"# Groq Docs API\n\nA Hono API server that fetches, caches, and processes Groq documentation pages with token counting and AI-generated metadata.\n\n## Features\n\n- Fetches documentation pages from Groq's console\n- Caches page content, metadata, token counts, and embeddings in SQLite\n- Token counting using tiktoken (GPT-4 encoding)\n- AI-generated metadata (categories, tags, use cases, sample questions)\n- Content embeddings generation (currently fake, ready for Groq API integration)\n- Hash-based change detection to skip unchanged pages during recalculation\n- Rate limiting with async-sema to avoid WAF blocking\n- RESTful API endpoints for accessing pages and managing cache\n- Modular code structure (utils.ts for utilities, groq.ts for Groq API functions)\n\n## First-Time Setup\n\n### 1. Initial Cache Population\n\nOn first run, the cache will be empty. You should populate it by running:\n\n```bash\nGET /cache/recalculate\n```\n\nThis will:\n- Fetch all pages from the URLs list\n- Calculate token counts for each page\n- Generate AI metadata (categories, tags, use cases, questions)\n- Generate embeddings for each page\n- Calculate content hashes for change detection\n- Store everything in the SQLite cache\n- Return a summary of what was cached\n\n**Important**: This will take some time as it processes all pages, generates metadata, and calculates tokens for each. Be patient!\n\n**Note**: On subsequent runs, unchanged pages (detected by content hash) will be automatically skipped unless you use force mode.\n\n### 2. Verify Cache\n\nCheck that the cache was populated:\n\n```bash\nGET /cache/stats\n```\n\nThis returns:\n```json\n{\n \"cachedPages\": 121,\n \"totalTokens\": 1234567\n}\n```\n\n## When to Recalculate\n\nYou should run `/cache/recalculate` in these scenarios:\n\n### ✅ Required Recalculations\n\n1. **First time setup** - Cache is empty\n2. **URL list changes** - You've added or removed URLs from the `urls` array\n3. **Content updates** - Documentation pages have been updated and you want fresh data\n4. **Token count needed** - You need accurate token counts for new content\n5. **Metadata refresh** - You want to regenerate AI metadata or embeddings\n\n### 🔄 Default Mode (Smart Recalculation)\n\nBy default, `/cache/recalculate` uses hash-based change detection:\n\n```bash\nGET /cache/recalculate\n```\n\n**Behavior:**\n- Fetches each page and calculates its content hash (SHA-256)\n- Compares hash with cached version\n- **Skips pages with unchanged content** (saves time and API calls)\n- Only processes pages that have changed\n- Still generates embeddings and metadata for changed pages\n\n**Response includes:**\n- `processed` - Number of pages actually processed\n- `skipped` - Number of pages skipped (unchanged)\n- `force` - Always `false` in default mode\n\n### ⚡ Force Mode (Recalculate Everything)\n\nTo force recalculation of all pages (ignoring hash checks):\n\n```bash\nGET /cache/recalculate?force=true\n```\n\n**Use cases:**\n- Regenerating all metadata/embeddings even if content unchanged\n- After updating metadata generation prompts\n- When you want to ensure everything is fresh\n\n### ⚠️ Partial Updates\n\nFor single page updates, you can use:\n\n```bash\nGET /cache/clear/:path\n```\n\nThis clears the cache for a specific page. The next time that page is requested via `/page/:path`, it will be fetched fresh and recached.\n\n### 🔄 Routine Maintenance\n\n- **Weekly**: Run recalculate (default mode) to catch any documentation updates efficiently\n- **After major docs changes**: Use force mode to regenerate everything\n- **When adding new pages**: Update the `urls` array, then run recalculate\n\n## API Endpoints\n\n### Page Endpoints\n\n#### `GET /page/docs`\nGet the root docs page (cached if available).\n\n#### `GET /page/:path`\nGet a specific page by path. Examples:\n- `/page/api-reference`\n- `/page/agentic-tooling/compound-beta`\n- `/page/model/llama-3.1-8b-instant`\n\n**Response includes:**\n- `url` - The source URL\n- `content` - Full page content with frontmatter\n- `charCount` - Character count\n- `tokenCount` - Token count (calculated with tiktoken)\n- All frontmatter fields flattened (title, description, image, etc.)\n\n**Caching**: Responses are cached. First request fetches and caches, subsequent requests are instant.\n\n#### `GET /list`\nGet a list of all available page paths.\n\n**Response:**\n```json\n[\n \"docs\",\n \"agentic-tooling\",\n \"api-reference\",\n ...\n]\n```\n\n#### `GET /search`\nSearch pages by query string.\n\n**Query Parameters:**\n- `q` (required) - Search query string\n- `limit` (optional) - Maximum number of results (default: 10)\n- `minScore` (optional) - Minimum score threshold (default: 0)\n\n**Example:**\n```bash\nGET /search?q=authentication&limit=5\n```\n\n**Response:**\n```json\n{\n \"query\": \"authentication\",\n \"results\": [\n {\n \"path\": \"api-reference\",\n \"url\": \"https://console.groq.com/docs/api-reference.md\",\n \"title\": \"API Reference\",\n \"score\": 45,\n \"snippet\": \"...authentication tokens are required for all API requests...\"\n },\n {\n \"path\": \"quickstart\",\n \"url\": \"https://console.groq.com/docs/quickstart.md\",\n \"title\": \"Quick Start\",\n \"score\": 32,\n \"snippet\": \"...get your API key for authentication...\"\n }\n ],\n \"totalResults\": 2,\n \"totalPages\": 121\n}\n```\n\n**Search Features:**\n- Keyword matching in titles and content\n- Metadata boost (tags, categories, use cases)\n- Score-based ranking\n- Content snippets around matches\n- Uses cached pages when available for faster results\n\n**Note**: Currently uses keyword-based search. Future versions will use embeddings for semantic search.\n\n#### `GET /data`\nGet metadata for all pages (does not use cache - fetches fresh).\n\n**Response:**\n```json\n{\n \"pages\": [\n {\n \"url\": \"...\",\n \"charCount\": 1234,\n \"frontmatter\": {...}\n }\n ],\n \"contents\": [...],\n \"totalPages\": 121,\n \"totalChars\": 1234567\n}\n```\n\n### Cache Management Endpoints\n\n#### `GET /cache/stats`\nGet cache statistics.\n\n**Response:**\n```json\n{\n \"cachedPages\": 121,\n \"totalTokens\": 1234567\n}\n```\n\n#### `GET /cache/clear`\nClear the entire cache.\n\n**Response:**\n```json\n{\n \"message\": \"Cache cleared\",\n \"success\": true\n}\n```\n\n#### `GET /cache/clear/:path`\nClear cache for a specific page.\n\n**Example:**\n```bash\nGET /cache/clear/api-reference\n```\n\n**Response:**\n```json\n{\n \"message\": \"Cache cleared for api-reference\",\n \"success\": true\n}\n```\n\n#### `GET /cache/recalculate`\nRecalculate pages with AI metadata and embeddings generation.\n\n**Query Parameters:**\n- `force` (optional): Set to `true` to force recalculation of all pages, ignoring hash checks\n\n**Default Mode** (no query params):\n```bash\nGET /cache/recalculate\n```\n\n**Force Mode**:\n```bash\nGET /cache/recalculate?force=true\n```\n\n**Response** (Default Mode):\n```json\n{\n \"message\": \"Recalculated 5 pages, skipped 116 unchanged pages\",\n \"results\": [\n {\n \"path\": \"api-reference\",\n \"url\": \"https://console.groq.com/docs/api-reference.md\",\n \"charCount\": 1234,\n \"tokenCount\": 567,\n \"title\": \"API Reference\",\n \"metadata\": {\n \"categories\": [\"API\", \"Reference\"],\n \"tags\": [\"api\", \"endpoints\", \"rest\"],\n \"useCases\": [\"Integrating with Groq API\"],\n \"questions\": [\"How do I authenticate?\", \"What endpoints are available?\"]\n }\n },\n {\n \"path\": \"docs\",\n \"skipped\": true,\n \"reason\": \"Content unchanged (hash matches)\"\n }\n ],\n \"totalPages\": 121,\n \"processed\": 5,\n \"skipped\": 116,\n \"withMetadata\": 5,\n \"withoutMetadata\": 0,\n \"cached\": true,\n \"force\": false\n}\n```\n\n**Response** (Force Mode):\n```json\n{\n \"message\": \"Recalculated 121 pages with AI metadata (force mode)\",\n \"results\": [...],\n \"totalPages\": 121,\n \"processed\": 121,\n \"skipped\": 0,\n \"force\": true\n}\n```\n\n**What it does:**\n- Fetches all pages (or skips unchanged ones in default mode)\n- Calculates token counts\n- Generates AI metadata (categories, tags, use cases, questions)\n- Generates embeddings (currently fake, ready for Groq API)\n- Calculates content hashes for change detection\n- Stores everything in cache\n\n**Important**: This can take several minutes depending on:\n- Number of pages to process (skipped pages are fast)\n- Network speed\n- Token calculation time\n- AI metadata generation time (uses Groq API)\n\n## Cache Behavior\n\n### How Caching Works\n\n1. **First Request**: \n - Check cache → Not found\n - Fetch from URL\n - Calculate tokens\n - Store in cache\n - Return data\n\n2. **Subsequent Requests**:\n - Check cache → Found\n - Return cached data immediately\n\n### Cache Storage\n\nCache is stored in SQLite with the following schema:\n\n```sql\nCREATE TABLE groq_docs_cache_v3 (\n url TEXT PRIMARY KEY,\n content TEXT NOT NULL,\n charCount INTEGER NOT NULL,\n tokenCount INTEGER,\n frontmatter TEXT NOT NULL,\n metadata TEXT,\n contentHash TEXT,\n embeddings TEXT,\n cachedAt INTEGER NOT NULL\n)\n```\n\n**Fields:**\n- `url` - Source URL (primary key)\n- `content` - Full page content with frontmatter\n- `charCount` - Character count\n- `tokenCount` - Token count (calculated with tiktoken)\n- `frontmatter` - Parsed frontmatter (JSON)\n- `metadata` - AI-generated metadata (categories, tags, use cases, questions)\n- `contentHash` - SHA-256 hash of content (for change detection)\n- `embeddings` - Content embeddings vector (JSON array)\n- `cachedAt` - Timestamp when cached\n\n### Cache Invalidation\n\nCache is invalidated when:\n- You manually clear it via `/cache/clear`\n- You recalculate via `/cache/recalculate`\n- Cache is cleared for a specific page via `/cache/clear/:path`\n\n**Note**: Cache does NOT automatically expire. If documentation changes, you must manually recalculate.\n\n## Adding New Pages\n\n1. **Add URL to the `urls` array** in `main.tsx`:\n ```typescript\n const urls = [\n // ... existing URLs\n \"https://console.groq.com/docs/new-page.md\",\n ];\n ```\n\n2. **Run recalculate**:\n ```bash\n POST /cache/recalculate\n ```\n\n3. **Verify**:\n ```bash\n GET /cache/stats\n GET /list # Should include your new page\n ```\n\n## Token Counting\n\nToken counts are calculated using [tiktoken](https://github.com/openai/tiktoken) with the `gpt-4` encoding (cl100k_base). This is the same encoding used by:\n- GPT-4\n- GPT-3.5-turbo\n- Many other OpenAI models\n\nToken counts are:\n- Calculated on first fetch\n- Stored in cache\n- Returned in API responses\n- Expensive to compute (which is why caching is important)\n\n## AI Metadata Generation\n\nEach page can have AI-generated metadata using Groq's chat completions API:\n\n- **Categories**: 2-4 broad categories (e.g., \"API\", \"Authentication\", \"Models\")\n- **Tags**: 5-10 specific tags/keywords\n- **Use Cases**: 2-4 practical use cases or scenarios\n- **Questions**: 5-10 questions users might ask\n\nMetadata is generated during `/cache/recalculate` and stored in the cache.\n\n## Search\n\nThe API includes a search endpoint (`/search`) that allows you to search across all documentation pages.\n\n### Current Implementation (Keyword-Based)\n\nCurrently uses keyword matching:\n- Searches in page titles and content\n- Boosts results matching metadata (tags, categories, use cases)\n- Returns ranked results with relevance scores\n- Includes content snippets around matches\n\n### Future Implementation (Semantic Search)\n\nThe search system is designed to support embeddings-based semantic search:\n- `generateEmbeddings()` - Generates embeddings (currently fake, ready for real API)\n- `vectorSearch()` - Vector similarity search function (ready to use when embeddings are real)\n- Will enable semantic understanding of queries (not just keyword matching)\n\n## Embeddings\n\nContent embeddings are generated for each page. Currently using a fake implementation (deterministic 384-dimensional vectors) that's ready to be replaced with actual embeddings API when available.\n\nEmbeddings are:\n- Generated during recalculation\n- Stored in cache\n- Will be used for semantic search and similarity matching (currently using keyword search)\n\n## Hash-Based Change Detection\n\nContent hashes (SHA-256) are calculated and stored for each page. This enables:\n\n- **Smart recalculation**: Skip unchanged pages automatically\n- **Efficient updates**: Only process pages that have actually changed\n- **Performance**: Significantly faster recalculation when most content is unchanged\n\nHashes are compared during `/cache/recalculate` (default mode) to determine if a page needs reprocessing.\n\n## Troubleshooting\n\n### Cache seems stale\nRun `/cache/recalculate` to refresh everything.\n\n### Page not found\n1. Check `/list` to see if the path exists\n2. Verify the URL is in the `urls` array\n3. Ensure the path matches the URL structure (e.g., `api-reference` for `/docs/api-reference.md`)\n\n### Token counts seem wrong\n1. Clear cache for that page: `POST /cache/clear/:path`\n2. Request the page again: `GET /page/:path`\n3. Or recalculate everything: `POST /cache/recalculate`\n\n### Performance issues\n- Use `/page/:path` endpoints (cached) instead of `/data` (uncached)\n- Check cache stats: `GET /cache/stats`\n- Ensure cache is populated before production use\n\n## Code Structure\n\nThe codebase is organized into modular files:\n\n- **`main.tsx`** - Main Hono app, routes, and URL definitions\n- **`utils.ts`** - Utility functions:\n - Cache management (getFromCache, setCache, clearCache, getCacheStats)\n - Content fetching (getTextFromUrl)\n - Frontmatter parsing (parseFrontmatter, addUrlSourceToFrontmatter)\n - Token counting (calculateTokenCount)\n - Hash calculation (calculateContentHash)\n - Rate limiting for fetches\n- **`groq.ts`** - Groq API functions:\n - Chat completions (groqChatCompletion)\n - Metadata generation (generatePageMetadata)\n- **`search.ts`** - Search and embeddings utilities:\n - Embeddings generation (generateEmbeddings) - fake implementation ready for real API\n - Search functions (searchPages) - keyword-based search (will use embeddings later)\n - Vector similarity search (vectorSearch) - ready for embeddings-based search\n\n## Development\n\n### Local Development\n\n```bash\ndeno run --allow-net --allow-env main.tsx\n```\n\n**Note**: SQLite caching is automatically disabled when running locally (detected via `valtown` environment variable). The app will work without caching, but cache-related endpoints will return appropriate messages.\n\n### Val Town\n\nThe app is configured to work with Val Town. Export uses:\n```typescript\nexport default (typeof Deno !== \"undefined\" && Deno.env.get(\"valtown\")) ? app.fetch : app;\n```\n\nSQLite caching is automatically enabled when running in Val Town (detected via `valtown` environment variable).\n\n### Environment Variables\n\n- `GROQ_API_KEY` - Required for AI metadata generation (optional, will disable metadata if not set)\n- `valtown` - Automatically set by Val Town (detects environment)\n\n## Performance Tips\n\n1. **Use default recalculate mode** - Automatically skips unchanged pages\n2. **Cache is your friend** - Always populate cache before production use\n3. **Rate limiting** - Built-in rate limiting prevents WAF blocking (1 request per 3 seconds for docs, 2 requests per second for Groq API)\n4. **Hash checking** - Default recalculation mode is much faster when most content is unchanged\n\n",[189],"6575fc7c-b8e7-11f0-ba05-0224a6c84d84","AGENTS.md","6575fd58-b8e7-11f0-ba05-0224a6c84d84",6,["D",1762196442671],"You are an advanced assistant specialized in generating Val Town code.\n\n## Core Guidelines\n\n- Ask clarifying questions when requirements are ambiguous\n- Provide complete, functional solutions rather than skeleton implementations\n- Test your logic against edge cases before presenting the final solution\n- Ensure all code follows Val Town's specific platform requirements\n- If a section of code that you're working on is getting too complex, consider refactoring it into subcomponents\n\n## Code Standards\n\n- Generate code in TypeScript or TSX\n- Add appropriate TypeScript types and interfaces for all data structures\n- Prefer official SDKs or libraries than writing API calls directly\n- Ask the user to supply API or library documentation if you are at all unsure about it\n- **Never bake in secrets into the code** - always use environment variables\n- Include comments explaining complex logic (avoid commenting obvious operations)\n- Follow modern ES6+ conventions and functional programming practices if possible\n\n## Types of triggers\n\n### 1. HTTP Trigger\n\n- Create web APIs and endpoints\n- Handle HTTP requests and responses\n- Example structure:\n\n```ts\nexport default async function (req: Request) {\n return new Response(\"Hello World\");\n}\n```\n\nFiles that are HTTP triggers have http in their name like `foobar.http.tsx`\n\n### 2. Cron Triggers\n\n- Run on a schedule\n- Use cron expressions for timing\n- Example structure:\n\n```ts\nexport default async function () {\n // Scheduled task code\n}\n```\n\nFiles that are Cron triggers have cron in their name like `foobar.cron.tsx`\n\n### 3. Email Triggers\n\n- Process incoming emails\n- Handle email-based workflows\n- Example structure:\n\n```ts\nexport default async function (email: Email) {\n // Process email\n}\n```\n\nFiles that are Email triggers have email in their name like `foobar.email.tsx`\n\n\n## Val Town Standard Libraries\n\nVal Town provides several hosted services and utility functions.\n\n### Blob Storage\n\n```ts\nimport { blob } from \"https://esm.town/v/std/blob\";\nawait blob.setJSON(\"myKey\", { hello: \"world\" });\nlet blobDemo = await blob.getJSON(\"myKey\");\nlet appKeys = await blob.list(\"app_\");\nawait blob.delete(\"myKey\");\n```\n\n### SQLite\n\n```ts\nimport { sqlite } from \"https://esm.town/v/stevekrouse/sqlite\";\nconst TABLE_NAME = 'todo_app_users_2';\n// Create table - do this before usage and change table name when modifying schema\nawait sqlite.execute(`CREATE TABLE IF NOT EXISTS ${TABLE_NAME} (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT NOT NULL\n)`);\n// Query data\nconst result = await sqlite.execute(`SELECT * FROM ${TABLE_NAME} WHERE id = ?`, [1]);\n```\n\nNote: When changing a SQLite table's schema, change the table's name (e.g., add _2 or _3) to create a fresh table.\n\n### OpenAI\n\n```ts\nimport { OpenAI } from \"https://esm.town/v/std/openai\";\nconst openai = new OpenAI();\nconst completion = await openai.chat.completions.create({\n messages: [\n { role: \"user\", content: \"Say hello in a creative way\" },\n ],\n model: \"gpt-4o-mini\",\n max_tokens: 30,\n});\n```\n\n### Email\n\n```ts\nimport { email } from \"https://esm.town/v/std/email\";\n// By default emails the owner of the val\nawait email({ \n subject: \"Hi\", \n text: \"Hi\", \n html: \"

Hi

\"\n});\n```\n\n## Val Town Utility Functions\n\nVal Town provides several utility functions to help with common project tasks.\n\n### Importing Utilities\n\nAlways import utilities with version pins to avoid breaking changes:\n\n```ts\nimport { parseProject, readFile, serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n```\n\n### Available Utilities\n\n\n#### **serveFile** - Serve project files with proper content types\n\nFor example, in Hono:\n\n```ts\n// serve all files in frontend/ and shared/\napp.get(\"/frontend/*\", c => serveFile(c.req.path, import.meta.url));\napp.get(\"/shared/*\", c => serveFile(c.req.path, import.meta.url));\n```\n\n#### **readFile** - Read files from within the project:\n\n```ts\n// Read a file from the project\nconst fileContent = await readFile(\"/frontend/index.html\", import.meta.url);\n```\n\n#### **listFiles** - List all files in the project\n\n```ts\nconst files = await listFiles(import.meta.url);\n```\n\n#### **parseProject** - Extract information about the current project from import.meta.url\n\nThis is useful for including info for linking back to a val, ie in \"view source\" urls:\n\n```ts\nconst projectVal = parseProject(import.meta.url);\nconsole.log(projectVal.username); // Owner of the project\nconsole.log(projectVal.name); // Project name\nconsole.log(projectVal.version); // Version number\nconsole.log(projectVal.branch); // Branch name\nconsole.log(projectVal.links.self.project); // URL to the project page\n```\n\nHowever, it's *extremely importing* to note that `parseProject` and other Standard Library utilities ONLY RUN ON THE SERVER.\nIf you need access to this data on the client, run it in the server and pass it to the client by splicing it into the HTML page\nor by making an API request for it.\n\n## Val Town Platform Specifics\n\n- **Redirects:** Use `return new Response(null, { status: 302, headers: { Location: \"/place/to/redirect\" }})` instead of `Response.redirect` which is broken\n- **Images:** Avoid external images or base64 images. Use emojis, unicode symbols, or icon fonts/libraries instead\n- **AI Image:** To inline generate an AI image use: `

`\n- **Storage:** DO NOT use the Deno KV module for storage\n- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods\n- **Weather Data:** Use open-meteo for weather data (doesn't require API keys) unless otherwise specified\n- **View Source:** Add a view source link by importing & using `import.meta.url.replace(\"ems.sh\", \"val.town)\"` (or passing this data to the client) and include `target=\"_top\"` attribute\n- **Error Debugging:** Add `` to HTML to capture client-side errors\n- **Error Handling:** Only use try...catch when there's a clear local resolution; Avoid catches that merely log or return 500s. Let errors bubble up with full context\n- **Environment Variables:** Use `Deno.env.get('keyname')` when you need to, but generally prefer APIs that don't require keys\n- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure compatibility on server and browser\n- **Storage Strategy:** Only use backend storage if explicitly required; prefer simple static client-side sites\n- **React Configuration:** When using React libraries, pin versions with `?deps=react@18.2.0,react-dom@18.2.0` and start the file with `/** @jsxImportSource https://esm.sh/react@18.2.0 */`\n- Ensure all React dependencies and sub-dependencies are pinned to the same version\n- **Styling:** Default to using TailwindCSS via `` unless otherwise specified\n\n## Project Structure and Design Patterns\n\n### Recommended Directory Structure\n```\n├── backend/\n│ ├── database/\n│ │ ├── migrations.ts # Schema definitions\n│ │ ├── queries.ts # DB query functions\n│ │ └── README.md\n│ └── routes/ # Route modules\n│ ├── [route].ts\n│ └── static.ts # Static file serving\n│ ├── index.ts # Main entry point\n│ └── README.md\n├── frontend/\n│ ├── components/\n│ │ ├── App.tsx\n│ │ └── [Component].tsx\n│ ├── favicon.svg\n│ ├── index.html # Main HTML template\n│ ├── index.tsx # Frontend JS entry point\n│ ├── README.md\n│ └── style.css\n├── README.md\n└── shared/\n ├── README.md\n └── utils.ts # Shared types and functions\n```\n\n### Backend (Hono) Best Practices\n\n- Hono is the recommended API framework\n- Main entry point should be `backend/index.ts`\n- **Static asset serving:** Use the utility functions to read and serve project files:\n ```ts\n import { readFile, serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n \n // serve all files in frontend/ and shared/\n app.get(\"/frontend/*\", c => serveFile(c.req.path, import.meta.url));\n app.get(\"/shared/*\", c => serveFile(c.req.path, import.meta.url));\n \n // For index.html, often you'll want to bootstrap with initial data\n app.get(\"/\", async c => {\n let html = await readFile(\"/frontend/index.html\", import.meta.url);\n \n // Inject data to avoid extra round-trips\n const initialData = await fetchInitialData();\n const dataScript = ``;\n \n html = html.replace(\"\", `${dataScript}`);\n return c.html(html);\n });\n ```\n- Create RESTful API routes for CRUD operations\n- Always include this snippet at the top-level Hono app to re-throwing errors to see full stack traces:\n ```ts\n // Unwrap Hono errors to see original error details\n app.onError((err, c) => {\n throw err;\n });\n ```\n\n### Database Patterns\n- Run migrations on startup or comment out for performance\n- Change table names when modifying schemas rather than altering\n- Export clear query functions with proper TypeScript typing\n\n## Common Gotchas and Solutions\n\n1. **Environment Limitations:** \n - Val Town runs on Deno in a serverless context, not Node.js\n - Code in `shared/` must work in both frontend and backend environments\n - Cannot use `Deno` keyword in shared code\n - Use `https://esm.sh` for imports that work in both environments\n\n2. **SQLite Peculiarities:**\n - Limited support for ALTER TABLE operations\n - Create new tables with updated schemas and copy data when needed\n - Always run table creation before querying\n\n3. **React Configuration:**\n - All React dependencies must be pinned to 18.2.0\n - Always include `@jsxImportSource https://esm.sh/react@18.2.0` at the top of React files\n - Rendering issues often come from mismatched React versions\n\n4. **File Handling:**\n - Val Town only supports text files, not binary\n - Use the provided utilities to read files across branches and forks\n - For files in the project, use `readFile` helpers\n\n5. **API Design:**\n - `fetch` handler is the entry point for HTTP vals\n - Run the Hono app with `export default app.fetch // This is the entry point for HTTP vals`\n\n",[196],"65892a86-b8e7-11f0-ba05-0224a6c84d84",".vtignore","65892b4e-b8e7-11f0-ba05-0224a6c84d84",9,["D",1762196442809],".git\n.vscode\n.cursorrules\n.DS_Store\nnode_modules\nvendor",[203],"7ecff464-b9ca-11f0-8b68-0224a6c84d84","utils","7ecff54a-b9ca-11f0-8b68-0224a6c84d84",49,["D",1762293981048],"directory",[210],"30dc0596-b901-11f0-a3b9-0224a6c84d84","testing","30dc0668-b901-11f0-a3b9-0224a6c84d84",28,["D",1762207521420],[217],"30c2711c-b901-11f0-b5de-0224a6c84d84","search","30c2722a-b901-11f0-b5de-0224a6c84d84",27,["D",1762207521254],[223],"31189d8a-b901-11f0-87ce-0224a6c84d84","data","31189e3e-b901-11f0-87ce-0224a6c84d84",29,["D",1762207521817],[229],"7eb3aa8e-b9ca-11f0-98dd-0224a6c84d84","answer","7eb3ab56-b9ca-11f0-98dd-0224a6c84d84",48,["D",1762293980863],[235],"pulls","branches","forks","envVars",{"_247":60,"_249":60},"connections",{"_247":60,"_248":60},"count","unfilledCount","emptyCount",{"_41":234,"_31":235,"_29":236,"_141":-5,"_39":40,"_38":237,"_143":47,"_36":466,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_284":467,"_26":468},{"_41":458,"_31":459,"_29":460,"_141":236,"_39":40,"_38":461,"_143":47,"_36":462,"_13":60,"_33":20,"_34":463,"_23":24,"_147":-5,"_284":464,"_26":465},{"_41":454,"_31":32,"_29":30,"_141":236,"_39":40,"_38":14,"_143":47,"_36":455,"_13":60,"_33":20,"_34":35,"_23":24,"_147":-5,"_284":456,"_26":457},{"_41":446,"_31":447,"_29":448,"_141":236,"_39":40,"_38":449,"_143":47,"_36":450,"_13":60,"_33":20,"_34":451,"_23":24,"_147":-5,"_284":452,"_26":453},{"_41":439,"_31":139,"_29":440,"_141":236,"_39":40,"_38":441,"_143":47,"_36":442,"_13":60,"_33":145,"_34":443,"_23":24,"_147":-5,"_284":444,"_26":445},{"_41":228,"_31":229,"_29":230,"_141":-5,"_39":40,"_38":231,"_143":47,"_36":436,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_284":437,"_26":438},{"_41":222,"_31":223,"_29":224,"_141":-5,"_39":40,"_38":225,"_143":47,"_36":433,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_284":434,"_26":435},{"_41":428,"_31":420,"_29":423,"_141":224,"_39":40,"_38":429,"_143":47,"_36":430,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_284":431,"_26":432},{"_41":422,"_31":421,"_29":415,"_141":423,"_39":40,"_38":424,"_143":47,"_36":425,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_284":426,"_26":427},{"_41":412,"_31":413,"_29":414,"_141":415,"_39":40,"_38":416,"_143":47,"_36":417,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_284":418,"_26":419},{"_41":404,"_31":405,"_29":406,"_141":224,"_39":40,"_38":407,"_143":24,"_36":408,"_13":60,"_33":145,"_34":409,"_23":24,"_147":-5,"_284":410,"_26":411},{"_41":396,"_31":397,"_29":398,"_141":224,"_39":40,"_38":399,"_143":47,"_36":400,"_13":60,"_33":145,"_34":401,"_23":24,"_147":-5,"_284":402,"_26":403},{"_41":388,"_31":389,"_29":390,"_141":224,"_39":40,"_38":391,"_143":47,"_36":392,"_13":60,"_33":145,"_34":393,"_23":24,"_147":-5,"_284":394,"_26":395},{"_41":380,"_31":381,"_29":382,"_141":224,"_39":40,"_38":383,"_143":47,"_36":384,"_13":60,"_33":145,"_34":385,"_23":24,"_147":-5,"_284":386,"_26":387},{"_41":372,"_31":373,"_29":374,"_141":224,"_39":40,"_38":375,"_143":47,"_36":376,"_13":60,"_33":145,"_34":377,"_23":24,"_147":-5,"_284":378,"_26":379},{"_41":364,"_31":365,"_29":366,"_141":224,"_39":40,"_38":367,"_143":24,"_36":368,"_13":60,"_33":145,"_34":369,"_23":24,"_147":-5,"_284":370,"_26":371},{"_41":356,"_31":357,"_29":358,"_141":224,"_39":40,"_38":359,"_143":47,"_36":360,"_13":60,"_33":145,"_34":361,"_23":24,"_147":-5,"_284":362,"_26":363},{"_41":349,"_31":139,"_29":350,"_141":224,"_39":40,"_38":351,"_143":24,"_36":352,"_13":60,"_33":145,"_34":353,"_23":24,"_147":-5,"_284":354,"_26":355},{"_41":216,"_31":217,"_29":218,"_141":-5,"_39":40,"_38":219,"_143":47,"_36":346,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_284":347,"_26":348},{"_41":338,"_31":339,"_29":340,"_141":218,"_39":40,"_38":341,"_143":24,"_36":342,"_13":60,"_33":145,"_34":343,"_23":24,"_147":-5,"_284":344,"_26":345},{"_41":330,"_31":331,"_29":332,"_141":218,"_39":40,"_38":333,"_143":24,"_36":334,"_13":60,"_33":145,"_34":335,"_23":24,"_147":-5,"_284":336,"_26":337},{"_41":322,"_31":323,"_29":324,"_141":218,"_39":40,"_38":325,"_143":47,"_36":326,"_13":60,"_33":145,"_34":327,"_23":24,"_147":-5,"_284":328,"_26":329},{"_41":314,"_31":315,"_29":316,"_141":218,"_39":40,"_38":317,"_143":24,"_36":318,"_13":60,"_33":145,"_34":319,"_23":24,"_147":-5,"_284":320,"_26":321},{"_41":209,"_31":210,"_29":211,"_141":-5,"_39":40,"_38":212,"_143":47,"_36":311,"_13":60,"_33":214,"_34":-5,"_23":24,"_147":-5,"_284":312,"_26":313},{"_41":202,"_31":203,"_29":204,"_141":-5,"_39":40,"_38":205,"_143":24,"_36":308,"_13":60,"_33":20,"_34":207,"_23":24,"_147":-5,"_284":309,"_26":310},{"_41":195,"_31":196,"_29":197,"_141":-5,"_39":40,"_38":198,"_143":47,"_36":305,"_13":60,"_33":20,"_34":200,"_23":24,"_147":-5,"_284":306,"_26":307},{"_41":188,"_31":189,"_29":190,"_141":-5,"_39":40,"_38":191,"_143":24,"_36":302,"_13":185,"_33":20,"_34":193,"_23":24,"_147":-5,"_284":303,"_26":304},{"_41":180,"_31":181,"_29":182,"_141":-5,"_39":40,"_38":183,"_143":24,"_36":299,"_13":185,"_33":20,"_34":186,"_23":24,"_147":-5,"_284":300,"_26":301},{"_41":173,"_31":174,"_29":175,"_141":-5,"_39":40,"_38":176,"_143":47,"_36":296,"_13":60,"_33":145,"_34":178,"_23":24,"_147":-5,"_284":297,"_26":298},{"_41":164,"_31":165,"_29":55,"_141":-5,"_39":40,"_38":166,"_143":24,"_36":293,"_13":168,"_33":169,"_34":170,"_23":24,"_147":171,"_284":294,"_26":295},{"_41":156,"_31":157,"_29":158,"_141":-5,"_39":40,"_38":159,"_143":24,"_36":290,"_13":161,"_33":20,"_34":162,"_23":24,"_147":-5,"_284":291,"_26":292},{"_41":149,"_31":150,"_29":151,"_141":-5,"_39":40,"_38":152,"_143":24,"_36":287,"_13":60,"_33":145,"_34":154,"_23":24,"_147":-5,"_284":288,"_26":289},{"_41":138,"_31":139,"_29":140,"_141":-5,"_39":40,"_38":142,"_143":47,"_36":283,"_13":60,"_33":145,"_34":146,"_23":24,"_147":-5,"_284":285,"_26":286},["D",1762200814128],"children",[],[139],["D",1762207522123],[],[150],["D",1762207522872],[],[157],["D",1762207522732],[],[165],["D",1762200814266],[],[174],["D",1762207522854],[],[181],["D",1762200814124],[],[189],["D",1762196442671],[],[196],["D",1762196442809],[],[203],["D",1762293981048],[],[210],"31b6d658-b901-11f0-bfbc-0224a6c84d84","test-search.ts","31b6d70c-b901-11f0-bfbc-0224a6c84d84",43,["D",1762207522693],"// Test script for search strategies\n// Run with: deno task test-search\n// Requires: Run `deno task recalculate` first to generate /data/latest.json\n\nimport \"jsr:@std/dotenv/load\";\nimport { getAllPagesForSearch } from \"../main.tsx\";\nimport { runSearchTest } from \"./search-harness.ts\";\nimport { questions } from \"./questions.ts\";\n\nasync function testSearchStrategies() {\n // Load cached data from latest.json\n let cachedData: any = null;\n try {\n const latestData = await Deno.readTextFile(\"./data/latest.json\");\n cachedData = JSON.parse(latestData);\n console.log(`Loaded cached data from /data/latest.json (${cachedData.totalPages} pages)`);\n } catch (error) {\n console.error(\"Failed to load /data/latest.json. Please run 'deno task recalculate' first.\");\n console.error(error);\n Deno.exit(1);\n }\n \n // Load actual pages with embeddings for search\n const pagesWithEmbeddings = await getAllPagesForSearch();\n console.log(`Loaded ${pagesWithEmbeddings.length} pages with embeddings for search`);\n \n // Load test questions\n const testQueries = questions;\n console.log(`Loaded ${testQueries.length} test questions\\n`);\n \n for (const query of testQueries) {\n console.log(`\\n${\"=\".repeat(60)}`);\n console.log(`Testing query: \"${query}\"`);\n console.log(`${\"=\".repeat(60)}`);\n \n const testResult = await runSearchTest(query, pagesWithEmbeddings, {\n limit: 10,\n minScore: 0,\n enableTiming: true, // Enable timing breakdown\n });\n \n if (testResult.error) {\n console.error(` ❌ Error: ${testResult.error}`);\n console.log(` ⏱️ Duration: ${testResult.durationMs.toFixed(2)}ms`);\n } else {\n console.log(` ✅ Found ${testResult.results.length} results in ${testResult.durationMs.toFixed(2)}ms\\n`);\n \n if (testResult.results.length === 0) {\n console.log(\" No results found.\");\n } else {\n testResult.results.forEach((result, index) => {\n console.log(` ${index + 1}. ${result.title || result.path}`);\n console.log(` Path: ${result.path}`);\n console.log(` Score: ${result.score.toFixed(2)}${result.metadata?.similarity ? ` (similarity: ${(result.metadata.similarity * 100).toFixed(2)}%)` : ''}`);\n if (result.snippet) {\n const snippet = result.snippet.length > 150 \n ? result.snippet.substring(0, 150) + '...' \n : result.snippet;\n console.log(` Snippet: ${snippet}`);\n }\n console.log('');\n });\n }\n }\n }\n \n console.log(`\\n${\"=\".repeat(60)}`);\n console.log(\"Test completed!\");\n console.log(`${\"=\".repeat(60)}\\n`);\n}\n\n// Run if executed directly\nif (import.meta.main) {\n testSearchStrategies().catch(console.error);\n}\n\n",[],[217,315],"3193ad5e-b901-11f0-a764-0224a6c84d84","search-harness.ts","3193ae26-b901-11f0-a764-0224a6c84d84",39,["D",1762207522627],"// Test harness for search functionality\n// Reusable function for testing search queries\n\nimport { searchPages } from \"../search/index.ts\";\nimport type { Page, SearchResult, SearchOptions } from \"../search/types.ts\";\n\nexport interface SearchTestResult {\n results: SearchResult[];\n durationMs: number;\n error?: string;\n}\n\n/**\n * Test harness function for running a single search query\n * @param query - The search query string\n * @param pages - Array of pages to search through\n * @param options - Search options (limit, minScore, etc.)\n * @returns Promise with results and timing information\n */\nexport async function runSearchTest(\n query: string,\n pages: Page[],\n options: SearchOptions = {}\n): Promise {\n const startTime = performance.now();\n \n try {\n const results = await searchPages(query, pages, options);\n const endTime = performance.now();\n const durationMs = endTime - startTime;\n \n return {\n results,\n durationMs,\n };\n } catch (error) {\n const endTime = performance.now();\n const durationMs = endTime - startTime;\n \n return {\n results: [],\n durationMs,\n error: error instanceof Error ? error.message : String(error),\n };\n }\n}\n\n",[],[217,323],"319c6fde-b901-11f0-a8ca-0224a6c84d84","recalculate.ts","319c70b0-b901-11f0-a8ca-0224a6c84d84",40,["D",1762207522645],"// Recalculate script - runs cache recalculation and saves to /data/latest.json and /data/mm-dd-yyyy.json\n// Run with: deno task recalculate\n\nimport \"jsr:@std/dotenv/load\";\nimport { urls } from \"../urls.ts\";\nimport {\n IS_VALTOWN,\n getFromCache,\n setCache,\n calculateContentHash,\n getTextFromUrl,\n parseFrontmatter,\n addUrlSourceToFrontmatter,\n calculateTokenCount,\n} from \"../utils.ts\";\nimport { generatePageMetadata } from \"../groq.ts\";\nimport { getActiveEmbeddingsFunction } from \"../search/index.ts\";\nimport { saveTestData } from \"../main.tsx\";\n\n// Load cached data from latest.json (for local hash checking)\nasync function loadLatestJson(): Promise | null> {\n if (IS_VALTOWN) {\n return null; // Use SQLite when in Val Town\n }\n \n try {\n const latestData = await Deno.readTextFile(\"./data/latest.json\");\n const data = JSON.parse(latestData);\n \n // Create a map of url -> cached data\n const cacheMap: Record = {};\n \n if (data.results && Array.isArray(data.results)) {\n for (const result of data.results) {\n if (result.url) {\n cacheMap[result.url] = {\n contentHash: result.contentHash,\n charCount: result.charCount,\n tokenCount: result.tokenCount,\n title: result.title,\n metadata: result.metadata,\n embeddings: result.embeddings || null,\n };\n }\n }\n }\n \n return cacheMap;\n } catch {\n // latest.json doesn't exist or is invalid - that's okay, just return null\n return null;\n }\n}\n\nasync function recalculate(force: boolean = false) {\n console.log(`Starting recalculation (force: ${force}, local: ${!IS_VALTOWN})...`);\n \n // Load latest.json for hash checking when running locally\n const latestJsonData = await loadLatestJson();\n if (latestJsonData && !force) {\n console.log(`Loaded ${Object.keys(latestJsonData).length} cached hashes from latest.json`);\n }\n \n const results: Array<{ \n path: string; \n url: string; \n charCount: number; \n tokenCount: number | undefined;\n title?: string;\n metadata?: any;\n contentHash?: string;\n embeddings?: number[] | null;\n error?: string;\n cacheError?: string;\n skipped?: boolean;\n reason?: string;\n }> = [];\n \n let processedCount = 0;\n let skippedCount = 0;\n \n const getPageByPath = async (pathParam: string, useCache: boolean = true) => {\n // Find the matching URL\n const matchingUrl = urls.find(url => {\n const match = url.match(/\\/docs\\/(.+?)\\.md$/);\n if (match) {\n return match[1] === pathParam;\n }\n if (url.endsWith(\"/docs.md\") && pathParam === \"docs\") {\n return true;\n }\n return false;\n });\n \n if (!matchingUrl) {\n return null;\n }\n \n // Try to get from cache first\n if (useCache) {\n const cached = await getFromCache(matchingUrl);\n if (cached) {\n return {\n url: cached.frontmatter?.urlSource || matchingUrl,\n content: cached.content,\n charCount: cached.charCount,\n tokenCount: cached.tokenCount,\n };\n }\n }\n \n // Fetch and process the single page\n const text = await getTextFromUrl(matchingUrl);\n const processedText = addUrlSourceToFrontmatter(text, matchingUrl);\n const charCount = processedText.length;\n const tokenCount = calculateTokenCount(processedText);\n \n return {\n url: matchingUrl,\n content: processedText,\n charCount,\n tokenCount,\n };\n };\n \n for (const url of urls) {\n // Extract path from URL\n const match = url.match(/\\/docs\\/(.+?)\\.md$/);\n const path = match ? match[1] : (url.endsWith(\"/docs.md\") ? \"docs\" : null);\n \n if (path) {\n console.log(`[${processedCount + 1}/${urls.length}] Processing ${path}...`);\n \n try {\n // Check cached hash if not forcing\n let shouldSkip = false;\n if (!force) {\n // Try SQLite cache first (if in Val Town)\n let cached = await getFromCache(url);\n \n // If no SQLite cache, try latest.json (for local development)\n let cachedHash: string | null = null;\n let cachedFromJson: any = null;\n \n if (cached) {\n cachedHash = cached.contentHash;\n } else if (latestJsonData && latestJsonData[url]) {\n cachedFromJson = latestJsonData[url];\n cachedHash = cachedFromJson.contentHash || null;\n }\n \n if (cachedHash) {\n // Fetch fresh content to check hash\n try {\n const pageData = await getPageByPath(path, false);\n if (pageData) {\n const newHash = await calculateContentHash(pageData.content);\n if (newHash === cachedHash) {\n shouldSkip = true;\n skippedCount++;\n console.log(` Skipped ${path} (content unchanged, hash: ${newHash.substring(0, 8)}...)`);\n \n // Use cached data from SQLite or latest.json\n if (cached) {\n results.push({\n path,\n url,\n charCount: cached.charCount,\n tokenCount: cached.tokenCount || undefined,\n title: (cached.frontmatter as any).title || path,\n metadata: cached.metadata || undefined,\n contentHash: cachedHash,\n embeddings: cached.embeddings || null,\n skipped: true,\n reason: \"Content unchanged (hash matches)\",\n });\n } else if (cachedFromJson) {\n results.push({\n path,\n url,\n charCount: cachedFromJson.charCount || 0,\n tokenCount: cachedFromJson.tokenCount || undefined,\n title: cachedFromJson.title || path,\n metadata: cachedFromJson.metadata || undefined,\n contentHash: cachedHash,\n embeddings: cachedFromJson.embeddings || null,\n skipped: true,\n reason: \"Content unchanged (hash matches)\",\n });\n }\n }\n }\n } catch (hashCheckError) {\n // If hash check fails, continue with processing\n console.debug(` Hash check failed for ${path}, continuing...`);\n }\n }\n }\n \n if (shouldSkip) {\n processedCount++;\n continue;\n }\n \n // Fetch without cache\n let pageData;\n try {\n pageData = await getPageByPath(path, false);\n } catch (fetchError) {\n const fetchErrorMessage = fetchError instanceof Error ? fetchError.message : String(fetchError);\n console.error(` Failed to fetch ${path}:`, fetchErrorMessage);\n throw new Error(`Fetch failed: ${fetchErrorMessage}`);\n }\n \n if (pageData) {\n const frontmatter = parseFrontmatter(pageData.content);\n const title = (frontmatter as any).title || path;\n \n // Calculate content hash\n const contentHash = await calculateContentHash(pageData.content);\n \n // Generate AI metadata\n const metadata = await generatePageMetadata(pageData.content, title);\n if (!metadata) {\n console.warn(` Metadata generation failed for ${path} (continuing without metadata)`);\n }\n \n // Generate embeddings using active strategy's embeddings function\n const generateEmbeddings = getActiveEmbeddingsFunction();\n let embeddings: number[] | null = null;\n let embeddingsError: string | undefined = undefined;\n \n try {\n embeddings = await generateEmbeddings(pageData.content);\n if (!embeddings) {\n embeddingsError = \"Embeddings generation returned null\";\n console.error(` ❌ Embeddings generation failed for ${path}: ${embeddingsError}`);\n }\n } catch (embedError) {\n const embedErrorMessage = embedError instanceof Error ? embedError.message : String(embedError);\n embeddingsError = `Embeddings generation threw error: ${embedErrorMessage}`;\n console.error(` ❌ Embeddings generation failed for ${path}: ${embeddingsError}`);\n // Don't throw - continue with null embeddings, but log the error\n }\n \n // Cache it with metadata, hash, and embeddings - track errors\n const cacheError = await setCache(url, {\n content: pageData.content,\n charCount: pageData.charCount,\n tokenCount: pageData.tokenCount || null,\n frontmatter,\n metadata,\n contentHash,\n embeddings,\n });\n \n results.push({ \n path, \n url, \n charCount: pageData.charCount, \n tokenCount: pageData.tokenCount,\n title,\n metadata,\n contentHash,\n embeddings: embeddings || null,\n ...(cacheError && { cacheError }),\n ...(embeddingsError && { embeddingsError }),\n });\n \n const statusParts = [\n `metadata: ${metadata ? 'yes' : 'no'}`,\n `embeddings: ${embeddings ? 'yes' : 'no'}`,\n ];\n \n if (embeddingsError) {\n statusParts.push(`embeddings error: ${embeddingsError.substring(0, 50)}...`);\n }\n if (cacheError) {\n statusParts.push(`cache error: ${cacheError}`);\n }\n \n const status = statusParts.join(', ');\n if (embeddingsError || cacheError) {\n console.warn(`Completed ${path} (${status})`);\n } else {\n console.log(`Completed ${path} (${status}, cached: yes)`);\n }\n }\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n console.error(`Error processing ${path}:`, errorMessage);\n results.push({\n path,\n url,\n charCount: 0,\n tokenCount: 0,\n error: errorMessage,\n });\n }\n \n processedCount++;\n }\n }\n \n const cacheErrors = results.filter(r => r.cacheError);\n const processedResults = results.filter(r => !r.skipped);\n \n const summary = {\n message: force \n ? `Recalculated ${processedResults.length} pages with AI metadata (force mode)` \n : `Recalculated ${processedResults.length} pages, skipped ${skippedCount} unchanged pages`,\n timestamp: new Date().toISOString(),\n results,\n totalPages: results.length,\n processed: processedResults.length,\n skipped: skippedCount,\n withMetadata: processedResults.filter(r => r.metadata).length,\n withoutMetadata: processedResults.filter(r => !r.metadata).length,\n cached: processedResults.length > 0 && cacheErrors.length === 0,\n cacheErrors: cacheErrors.length > 0 ? cacheErrors.map(r => ({ path: r.path, error: r.cacheError })) : undefined,\n force,\n };\n \n // Save to both latest.json and dated file\n await saveTestData(summary);\n console.log(\"\\nRecalculation completed!\");\n \n return summary;\n}\n\n// Run if executed directly\nif (import.meta.main) {\n const force = Deno.args.includes(\"--force\") || Deno.args.includes(\"-f\");\n recalculate(force).catch(console.error);\n}\n\n",[],[217,331],"31a38e68-b901-11f0-a3b9-0224a6c84d84","questions.ts","31a38f30-b901-11f0-a3b9-0224a6c84d84",41,["D",1762207522633],"// Test questions for search testing\n// Full sentence questions about Groq\n\nexport const questions: string[] = [\n \"What is Compound and how does it work?\",\n // \"How do I authenticate with the Groq API?\",\n // \"What are the rate limits for Groq models?\",\n // \"How do I integrate Groq with my JavaScript application?\",\n // \"What is the difference between compound and compound-mini?\",\n // \"Can I use Groq for real-time web search?\",\n // \"How do I get started with Groq's API?\",\n // \"What models are available on Groq?\",\n // \"How does Groq's Compound AI system work?\",\n // \"Can I use custom tools with Groq's Compound AI?\",\n];\n\n",[],[217,339],["D",1762207521420],[269,270,271,272],[217],"31528cd4-b901-11f0-a3b9-0224a6c84d84","31528d88-b901-11f0-a3b9-0224a6c84d84",32,["D",1762207522155],"// Shared utilities for search strategies\n\n// Calculate cosine similarity between two embedding vectors\nexport const cosineSimilarity = (vecA: number[], vecB: number[]): number => {\n if (vecA.length !== vecB.length) {\n return 0;\n }\n \n let dotProduct = 0;\n let normA = 0;\n let normB = 0;\n \n for (let i = 0; i < vecA.length; i++) {\n dotProduct += vecA[i] * vecB[i];\n normA += vecA[i] * vecA[i];\n normB += vecB[i] * vecB[i];\n }\n \n if (normA === 0 || normB === 0) {\n return 0;\n }\n \n return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));\n};\n\n// Helper function to generate snippets\nexport const generateSnippet = (content: string, queryWords: string[], queryLower: string): string => {\n const contentLower = content.toLowerCase();\n const firstMatchIndex = contentLower.indexOf(queryWords[0]);\n \n if (firstMatchIndex >= 0) {\n const start = Math.max(0, firstMatchIndex - 50);\n const end = Math.min(content.length, firstMatchIndex + queryWords[0].length + 150);\n let snippet = content.substring(start, end);\n if (start > 0) snippet = '...' + snippet;\n if (end < content.length) snippet = snippet + '...';\n return snippet;\n }\n \n return content.substring(0, 200) + '...';\n};\n\n",[],[223,139],"316a968a-b901-11f0-9996-0224a6c84d84","types.ts","316a973e-b901-11f0-9996-0224a6c84d84",34,["D",1762207522301],"// Search strategy types and interfaces\n\nexport type SearchResult = {\n path: string;\n url: string;\n title?: string;\n score: number;\n snippet?: string;\n metadata?: {\n strategy?: string;\n [key: string]: any;\n };\n};\n\nexport type Page = {\n path: string;\n url: string;\n content: string;\n title?: string;\n embeddings?: number[] | null;\n metadata?: any;\n};\n\nexport type SearchOptions = {\n limit?: number;\n minScore?: number;\n [key: string]: any;\n};\n\nexport type SearchStrategy = {\n name: string;\n description: string;\n search: (query: string, pages: Page[], options: SearchOptions) => Promise;\n};\n\n",[],[223,357],"31884234-b901-11f0-b784-0224a6c84d84","transformers-cosine.ts","31884324-b901-11f0-b784-0224a6c84d84",38,["D",1762207522387],"// Transformers.js + Cosine Similarity Strategy: Local embeddings in browser/Deno\n// Fastest option - no API calls, runs entirely client-side\n// Model: all-MiniLM-L6-v2 (80MB, ~384 dimensions, very fast)\n\nimport type { SearchStrategy, SearchResult, Page, SearchOptions } from \"./types.ts\";\nimport { generateSnippet, cosineSimilarity } from \"./utils.ts\";\n\n// Lazy-loaded pipeline (cached after first load)\nlet embeddingPipeline: any = null;\nlet pipelineLoading: Promise | null = null;\n\nasync function getEmbeddingPipeline() {\n // Return cached pipeline if already loaded\n if (embeddingPipeline) {\n return embeddingPipeline;\n }\n \n // If loading in progress, wait for it\n if (pipelineLoading) {\n return pipelineLoading;\n }\n \n // Start loading pipeline\n pipelineLoading = (async () => {\n try {\n // Import transformers.js - use npm: prefix for Deno compatibility\n // NOTE: transformers.js is primarily designed for browsers. In Deno, it may require --allow-ffi\n // For browser usage, this will work seamlessly. For Deno, you may need additional permissions.\n const { pipeline } = await import(\"npm:@huggingface/transformers@latest\");\n \n // Load feature extraction pipeline with all-MiniLM-L6-v2 model\n // This is a small, fast model optimized for embeddings (80MB, ~384 dims)\n embeddingPipeline = await pipeline(\n 'feature-extraction',\n 'Xenova/all-MiniLM-L6-v2',\n {\n // Use CPU - WebGPU might not be available in all environments\n device: 'cpu',\n dtype: 'fp32',\n }\n );\n \n return embeddingPipeline;\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n const fullError = `Failed to load transformers.js pipeline: ${errorMessage}\\n` +\n `NOTE: transformers.js is primarily designed for browser environments. ` +\n `If running in Deno, you may need --allow-ffi permissions, or use a different embedding strategy.`;\n console.error(fullError);\n throw new Error(fullError);\n } finally {\n pipelineLoading = null;\n }\n })();\n \n return pipelineLoading;\n}\n\n// Generate embeddings using transformers.js (runs locally, no API calls)\nexport const generateEmbeddings = async (content: string): Promise => {\n try {\n const pipeline = await getEmbeddingPipeline();\n \n // Generate embeddings - returns a tensor, we need to extract the array\n const output = await pipeline(content, {\n pooling: 'mean',\n normalize: true,\n });\n \n // Extract the embedding vector from the tensor\n // Transformers.js returns a Tensor object - handle different formats\n if (output && typeof output === 'object') {\n // Check for .data property (common tensor format)\n if (output.data && Array.isArray(output.data)) {\n return output.data;\n }\n \n // Check if it's a nested array (tensor shape)\n if (Array.isArray(output)) {\n // Flatten if nested\n if (Array.isArray(output[0])) {\n return output[0]; // Return first row if 2D\n }\n return output;\n }\n \n // Try accessing tensor properties\n if (output.size && output.data) {\n return Array.from(output.data);\n }\n \n // Try tolist() method if available\n if (typeof output.tolist === 'function') {\n const list = output.tolist();\n return Array.isArray(list[0]) ? list[0] : list;\n }\n }\n \n // Fallback: try to convert to array\n return Array.from(output as any);\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n console.error(\"Transformers.js embeddings failed:\", errorMessage);\n return null;\n }\n};\n\nexport const searchStrategy: SearchStrategy = {\n name: \"transformers-cosine\",\n description: \"Semantic search using Transformers.js local embeddings with cosine similarity (fastest, no API calls)\",\n search: async (query: string, pages: Page[], options: SearchOptions = {}): Promise => {\n const limit = options.limit || 10;\n const minSimilarity = (options.minScore || 0) / 100; // Convert to 0-1 scale\n const enableTiming = options.enableTiming || false;\n \n const timings: Record = {};\n const startTime = performance.now();\n \n // Generate query embedding (local, no API call)\n const queryEmbedStart = performance.now();\n const queryEmbedding = await generateEmbeddings(query);\n if (enableTiming) {\n timings.queryEmbedding = performance.now() - queryEmbedStart;\n }\n \n if (!queryEmbedding) {\n console.warn(\"Query embedding generation failed, returning empty results\");\n return [];\n }\n \n // Calculate cosine similarity for each page\n const similarityStart = performance.now();\n const scoredPages: Array<{ page: Page; similarity: number }> = [];\n \n for (const page of pages) {\n const pageEmbedding = page.embeddings;\n if (!pageEmbedding || pageEmbedding.length !== queryEmbedding.length) {\n continue; // Skip pages without embeddings or wrong dimension\n }\n \n const similarity = cosineSimilarity(queryEmbedding, pageEmbedding);\n if (similarity >= minSimilarity) {\n scoredPages.push({ page, similarity });\n }\n }\n \n if (enableTiming) timings.similarity = performance.now() - similarityStart;\n \n // Sort by similarity (descending) and limit\n const sortStart = performance.now();\n scoredPages.sort((a, b) => b.similarity - a.similarity);\n const topPages = scoredPages.slice(0, limit);\n if (enableTiming) timings.sort = performance.now() - sortStart;\n \n // Transform to SearchResult format\n const transformStart = performance.now();\n const queryWords = query.toLowerCase().split(/\\s+/).filter(w => w.length > 0);\n const results: SearchResult[] = topPages.map(({ page, similarity }) => ({\n path: page.path,\n url: page.url,\n title: page.title || page.path,\n score: similarity * 100, // Convert to 0-100 scale\n snippet: generateSnippet(page.content, queryWords, query.toLowerCase()),\n metadata: {\n strategy: \"transformers-cosine\",\n similarity,\n ...(enableTiming && { timings }),\n },\n }));\n if (enableTiming) timings.transform = performance.now() - transformStart;\n \n if (enableTiming) {\n timings.total = performance.now() - startTime;\n console.log(` ⏱️ Timing breakdown:`);\n console.log(` Query embedding: ${timings.queryEmbedding?.toFixed(2)}ms (local model - no API)`);\n console.log(` Cosine similarity: ${timings.similarity?.toFixed(2)}ms`);\n console.log(` Sort: ${timings.sort?.toFixed(2)}ms`);\n console.log(` Transform: ${timings.transform?.toFixed(2)}ms`);\n console.log(` Total: ${timings.total?.toFixed(2)}ms`);\n }\n \n return results;\n },\n};\n\n",[],[223,365],"3181e164-b901-11f0-a3b9-0224a6c84d84","placeholder.ts","3181e22c-b901-11f0-a3b9-0224a6c84d84",37,["D",1762207522458],"// Placeholder Strategy: Keyword-based search (current default)\n\nimport type { SearchStrategy, SearchResult, Page, SearchOptions } from \"./types.ts\";\nimport { generateSnippet } from \"./utils.ts\";\n\n// Fake embeddings function for placeholder (not actually used, but kept for interface consistency)\nexport const generateEmbeddings = async (content: string): Promise => {\n // Not used in placeholder strategy, but kept for consistency\n // Returns fake embeddings for caching purposes\n console.debug(\"Generating fake embeddings for placeholder strategy\");\n \n const fakeEmbedding: number[] = [];\n const hash = content.split('').reduce((acc, char) => acc + char.charCodeAt(0), 0);\n \n for (let i = 0; i < 384; i++) {\n const value = Math.sin(hash + i) * 0.5 + 0.5;\n fakeEmbedding.push(value);\n }\n \n return fakeEmbedding;\n};\n\nexport const searchStrategy: SearchStrategy = {\n name: \"placeholder\",\n description: \"Keyword-based search using title, content, and metadata matching\",\n search: async (query: string, pages: Page[], options: SearchOptions = {}): Promise => {\n const limit = options.limit || 10;\n const minScore = options.minScore || 0;\n \n const queryLower = query.toLowerCase();\n const queryWords = queryLower.split(/\\s+/).filter(w => w.length > 0);\n \n const results: SearchResult[] = [];\n \n for (const page of pages) {\n let score = 0;\n const contentLower = page.content.toLowerCase();\n const titleLower = (page.title || page.path).toLowerCase();\n \n // Title matches are worth more\n for (const word of queryWords) {\n if (titleLower.includes(word)) {\n score += 10;\n }\n // Count occurrences in content\n const contentMatches = (contentLower.match(new RegExp(word, 'g')) || []).length;\n score += Math.min(contentMatches, 5); // Cap at 5 points per word\n }\n \n // Exact phrase match bonus\n if (contentLower.includes(queryLower)) {\n score += 20;\n }\n \n // Metadata boost (if query matches tags or categories)\n if (page.metadata) {\n const tags = (page.metadata.tags || []).join(' ').toLowerCase();\n const categories = (page.metadata.categories || []).join(' ').toLowerCase();\n const useCases = (page.metadata.useCases || []).join(' ').toLowerCase();\n \n for (const word of queryWords) {\n if (tags.includes(word)) score += 3;\n if (categories.includes(word)) score += 2;\n if (useCases.includes(word)) score += 2;\n }\n }\n \n if (score > minScore) {\n results.push({\n path: page.path,\n url: page.url,\n title: page.title,\n score,\n snippet: generateSnippet(page.content, queryWords, queryLower),\n metadata: {\n strategy: \"placeholder\",\n },\n });\n }\n }\n \n // Sort by score descending\n results.sort((a, b) => b.score - a.score);\n \n return results.slice(0, limit);\n },\n};\n\n",[],[223,373],"314db04c-b901-11f0-a764-0224a6c84d84","openai-orama.ts","314db0ec-b901-11f0-a764-0224a6c84d84",31,["D",1762207522111],"// OpenAI + Orama Strategy: Semantic search using OpenAI embeddings and Orama\n// Faster than JigsawStack (~100-200ms vs ~550ms for query embeddings)\n\nimport type { SearchStrategy, SearchResult, Page, SearchOptions } from \"./types.ts\";\nimport { generateSnippet } from \"./utils.ts\";\nimport { create, insertMultiple, search } from \"npm:@orama/orama@latest\";\n\n// OpenAI embeddings function\nexport const generateEmbeddings = async (content: string): Promise => {\n const OPENAI_API_KEY = Deno.env.get(\"OPENAI_API_KEY\");\n const OPENAI_API_URL = \"https://api.openai.com/v1/embeddings\";\n \n if (!OPENAI_API_KEY) {\n console.warn(\"OPENAI_API_KEY not found - embeddings disabled\");\n return null;\n }\n \n try {\n const response = await fetch(OPENAI_API_URL, {\n method: \"POST\",\n headers: {\n \"Authorization\": `Bearer ${OPENAI_API_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n model: \"text-embedding-3-small\", // Fast and efficient model\n input: content,\n }),\n });\n \n if (!response.ok) {\n const errorText = await response.text().catch(() => response.statusText);\n throw new Error(`OpenAI API error: ${response.status} ${response.statusText} - ${errorText.substring(0, 200)}`);\n }\n \n const data = await response.json();\n \n if (data.data && Array.isArray(data.data) && data.data.length > 0) {\n return data.data[0].embedding; // Return the embedding vector\n }\n \n return null;\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n console.error(\"OpenAI embeddings failed:\", errorMessage);\n return null;\n }\n};\n\n// No caching for query embeddings - we want to benchmark actual API performance\n\nexport const searchStrategy: SearchStrategy = {\n name: \"openai-orama\",\n description: \"Semantic search using OpenAI embeddings with Orama vector search (faster than JigsawStack)\",\n search: async (query: string, pages: Page[], options: SearchOptions = {}): Promise => {\n const limit = options.limit || 10;\n const minSimilarity = (options.minScore || 0) / 100; // Convert to 0-1 scale\n const enableTiming = options.enableTiming || false;\n \n const timings: Record = {};\n const startTime = performance.now();\n \n // Generate query embedding (no caching - benchmarking actual API performance)\n const queryEmbedStart = performance.now();\n const queryEmbedding = await generateEmbeddings(query);\n if (enableTiming) {\n timings.queryEmbedding = performance.now() - queryEmbedStart;\n }\n \n if (!queryEmbedding) {\n console.warn(\"Query embedding generation failed, returning empty results\");\n return [];\n }\n \n // Determine embedding dimension from query (or first page with embeddings)\n const embeddingDimension = queryEmbedding.length;\n if (embeddingDimension === 0) {\n return [];\n }\n \n // Create Orama database with vector field\n const dbCreateStart = performance.now();\n const db = await create({\n schema: {\n path: \"string\",\n url: \"string\",\n title: \"string\",\n content: \"string\",\n embedding: `vector[${embeddingDimension}]`,\n },\n });\n if (enableTiming) timings.dbCreate = performance.now() - dbCreateStart;\n \n // Prepare documents with embeddings for insertion\n const documents: Array<{\n path: string;\n url: string;\n title: string;\n content: string;\n embedding: number[];\n }> = [];\n \n // Collect pages with embeddings\n const docPrepStart = performance.now();\n for (const page of pages) {\n // Use cached embeddings if available, otherwise generate\n let pageEmbedding = page.embeddings;\n if (!pageEmbedding) {\n // Generate embedding if not cached (should be cached from recalculate, but handle missing)\n pageEmbedding = await generateEmbeddings(page.content);\n if (!pageEmbedding || pageEmbedding.length !== embeddingDimension) {\n continue; // Skip pages without embeddings or wrong dimension\n }\n }\n \n // Ensure embedding dimension matches\n if (pageEmbedding.length !== embeddingDimension) {\n continue;\n }\n \n documents.push({\n path: page.path,\n url: page.url,\n title: page.title || page.path,\n content: page.content,\n embedding: pageEmbedding,\n });\n }\n if (enableTiming) timings.docPrep = performance.now() - docPrepStart;\n \n // Insert all documents into Orama\n const insertStart = performance.now();\n if (documents.length > 0) {\n await insertMultiple(db, documents);\n } else {\n return []; // No documents to search\n }\n if (enableTiming) timings.insert = performance.now() - insertStart;\n \n // Perform vector similarity search using Orama\n const searchStart = performance.now();\n const searchResults = await search(db, {\n mode: \"vector\",\n vector: {\n value: queryEmbedding,\n property: \"embedding\",\n },\n similarity: minSimilarity,\n limit,\n includeVectors: false, // Don't need vectors in response\n });\n if (enableTiming) timings.search = performance.now() - searchStart;\n \n // Transform Orama results to SearchResult format\n const transformStart = performance.now();\n const results: SearchResult[] = searchResults.hits.map((hit: any) => {\n const page = pages.find(p => p.path === hit.document.path);\n const queryWords = query.toLowerCase().split(/\\s+/).filter(w => w.length > 0);\n \n return {\n path: hit.document.path,\n url: hit.document.url,\n title: hit.document.title,\n score: (hit.score || 0) * 100, // Convert similarity to score (0-100)\n snippet: page ? generateSnippet(page.content, queryWords, query.toLowerCase()) : hit.document.content.substring(0, 200) + '...',\n metadata: {\n strategy: \"openai-orama\",\n similarity: hit.score,\n ...(enableTiming && { timings }),\n },\n };\n });\n if (enableTiming) timings.transform = performance.now() - transformStart;\n \n if (enableTiming) {\n timings.total = performance.now() - startTime;\n console.log(` ⏱️ Timing breakdown:`);\n console.log(` Query embedding: ${timings.queryEmbedding?.toFixed(2)}ms (API call)`);\n console.log(` DB create: ${timings.dbCreate?.toFixed(2)}ms`);\n console.log(` Doc prep: ${timings.docPrep?.toFixed(2)}ms`);\n console.log(` Insert: ${timings.insert?.toFixed(2)}ms`);\n console.log(` Search: ${timings.search?.toFixed(2)}ms`);\n console.log(` Transform: ${timings.transform?.toFixed(2)}ms`);\n console.log(` Total: ${timings.total?.toFixed(2)}ms`);\n }\n \n return results;\n },\n};\n\n",[],[223,381],"31459b96-b901-11f0-9996-0224a6c84d84","openai-cosine.ts","31459c22-b901-11f0-9996-0224a6c84d84",30,["D",1762207522106],"// OpenAI + Cosine Similarity Strategy: Direct cosine similarity calculation\n// Fastest for small datasets (<100 pages) - no DB overhead\n\nimport type { SearchStrategy, SearchResult, Page, SearchOptions } from \"./types.ts\";\nimport { generateSnippet, cosineSimilarity } from \"./utils.ts\";\n\n// OpenAI embeddings function\nexport const generateEmbeddings = async (content: string): Promise => {\n const OPENAI_API_KEY = Deno.env.get(\"OPENAI_API_KEY\");\n const OPENAI_API_URL = \"https://api.openai.com/v1/embeddings\";\n \n if (!OPENAI_API_KEY) {\n console.warn(\"OPENAI_API_KEY not found - embeddings disabled\");\n return null;\n }\n \n try {\n const response = await fetch(OPENAI_API_URL, {\n method: \"POST\",\n headers: {\n \"Authorization\": `Bearer ${OPENAI_API_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n model: \"text-embedding-3-small\", // Fast and efficient model\n input: content,\n }),\n });\n \n if (!response.ok) {\n const errorText = await response.text().catch(() => response.statusText);\n throw new Error(`OpenAI API error: ${response.status} ${response.statusText} - ${errorText.substring(0, 200)}`);\n }\n \n const data = await response.json();\n \n if (data.data && Array.isArray(data.data) && data.data.length > 0) {\n return data.data[0].embedding; // Return the embedding vector\n }\n \n return null;\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n console.error(\"OpenAI embeddings failed:\", errorMessage);\n return null;\n }\n};\n\n// No caching for query embeddings - we want to benchmark actual API performance\n\n\nexport const searchStrategy: SearchStrategy = {\n name: \"openai-cosine\",\n description: \"Semantic search using OpenAI embeddings with direct cosine similarity (fastest for small datasets)\",\n search: async (query: string, pages: Page[], options: SearchOptions = {}): Promise => {\n const limit = options.limit || 10;\n const minSimilarity = (options.minScore || 0) / 100; // Convert to 0-1 scale\n const enableTiming = options.enableTiming || false;\n \n const timings: Record = {};\n const startTime = performance.now();\n \n // Generate query embedding (no caching - benchmarking actual API performance)\n const queryEmbedStart = performance.now();\n const queryEmbedding = await generateEmbeddings(query);\n if (enableTiming) {\n timings.queryEmbedding = performance.now() - queryEmbedStart;\n }\n \n if (!queryEmbedding) {\n console.warn(\"Query embedding generation failed, returning empty results\");\n return [];\n }\n \n // Calculate cosine similarity for each page\n const similarityStart = performance.now();\n const scoredPages: Array<{ page: Page; similarity: number }> = [];\n \n for (const page of pages) {\n const pageEmbedding = page.embeddings;\n if (!pageEmbedding || pageEmbedding.length !== queryEmbedding.length) {\n continue; // Skip pages without embeddings or wrong dimension\n }\n \n const similarity = cosineSimilarity(queryEmbedding, pageEmbedding);\n if (similarity >= minSimilarity) {\n scoredPages.push({ page, similarity });\n }\n }\n \n if (enableTiming) timings.similarity = performance.now() - similarityStart;\n \n // Sort by similarity (descending) and limit\n const sortStart = performance.now();\n scoredPages.sort((a, b) => b.similarity - a.similarity);\n const topPages = scoredPages.slice(0, limit);\n if (enableTiming) timings.sort = performance.now() - sortStart;\n \n // Transform to SearchResult format\n const transformStart = performance.now();\n const queryWords = query.toLowerCase().split(/\\s+/).filter(w => w.length > 0);\n const results: SearchResult[] = topPages.map(({ page, similarity }) => ({\n path: page.path,\n url: page.url,\n title: page.title || page.path,\n score: similarity * 100, // Convert to 0-100 scale\n snippet: generateSnippet(page.content, queryWords, query.toLowerCase()),\n metadata: {\n strategy: \"openai-cosine\",\n similarity,\n ...(enableTiming && { timings }),\n },\n }));\n if (enableTiming) timings.transform = performance.now() - transformStart;\n \n if (enableTiming) {\n timings.total = performance.now() - startTime;\n console.log(` ⏱️ Timing breakdown:`);\n console.log(` Query embedding: ${timings.queryEmbedding?.toFixed(2)}ms (API call)`);\n console.log(` Cosine similarity: ${timings.similarity?.toFixed(2)}ms`);\n console.log(` Sort: ${timings.sort?.toFixed(2)}ms`);\n console.log(` Transform: ${timings.transform?.toFixed(2)}ms`);\n console.log(` Total: ${timings.total?.toFixed(2)}ms`);\n }\n \n return results;\n },\n};\n\n",[],[223,389],"315f55ae-b901-11f0-8f9e-0224a6c84d84","jigsawstack-orama.ts","315f56bc-b901-11f0-8f9e-0224a6c84d84",33,["D",1762207522117],"// JigsawStack + Orama Strategy: Semantic search using JigsawStack embeddings and Orama\n\nimport type { SearchStrategy, SearchResult, Page, SearchOptions } from \"./types.ts\";\nimport { generateSnippet } from \"./utils.ts\";\nimport { create, insertMultiple, search } from \"npm:@orama/orama@latest\";\n\n// JigsawStack embeddings function (v2 API)\nexport const generateEmbeddings = async (content: string): Promise => {\n const JIGSAWSTACK_API_KEY = Deno.env.get(\"JIGSAWSTACK_API_KEY\");\n const JIGSAWSTACK_API_URL = \"https://api.jigsawstack.com/v2/embedding\";\n \n if (!JIGSAWSTACK_API_KEY) {\n console.warn(\"JIGSAWSTACK_API_KEY not found - embeddings disabled\");\n return null;\n }\n \n try {\n const response = await fetch(JIGSAWSTACK_API_URL, {\n method: \"POST\",\n headers: {\n \"X-Api-Key\": JIGSAWSTACK_API_KEY,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n text: content,\n type: \"text\",\n }),\n });\n \n if (!response.ok) {\n const errorText = await response.text().catch(() => response.statusText);\n throw new Error(`JigsawStack API error: ${response.status} ${response.statusText} - ${errorText.substring(0, 200)}`);\n }\n \n const data = await response.json();\n \n // JigsawStack v2 returns: { success: true, embeddings: [[...]], chunks: [...], _usage: {...} }\n // embeddings is an array of arrays, we want the first embedding vector\n if (data.success && data.embeddings && Array.isArray(data.embeddings) && data.embeddings.length > 0) {\n return data.embeddings[0]; // Return the first embedding vector\n }\n \n return null;\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n console.error(\"JigsawStack embeddings failed:\", errorMessage);\n return null;\n }\n};\n\nexport const searchStrategy: SearchStrategy = {\n name: \"jigsawstack-orama\",\n description: \"Semantic search using JigsawStack embeddings with Orama vector search\",\n search: async (query: string, pages: Page[], options: SearchOptions = {}): Promise => {\n const limit = options.limit || 10;\n const minSimilarity = (options.minScore || 0) / 100; // Convert to 0-1 scale\n const enableTiming = options.enableTiming || false;\n \n const timings: Record = {};\n const startTime = performance.now();\n \n // Generate query embedding (this is the main bottleneck - external API call)\n const queryEmbedStart = performance.now();\n const queryEmbedding = await generateEmbeddings(query);\n if (enableTiming) timings.queryEmbedding = performance.now() - queryEmbedStart;\n \n if (!queryEmbedding) {\n console.warn(\"Query embedding generation failed, returning empty results\");\n return [];\n }\n \n // Determine embedding dimension from query (or first page with embeddings)\n const embeddingDimension = queryEmbedding.length;\n if (embeddingDimension === 0) {\n return [];\n }\n \n // Create Orama database with vector field\n const dbCreateStart = performance.now();\n const db = await create({\n schema: {\n path: \"string\",\n url: \"string\",\n title: \"string\",\n content: \"string\",\n embedding: `vector[${embeddingDimension}]`,\n },\n });\n if (enableTiming) timings.dbCreate = performance.now() - dbCreateStart;\n \n // Prepare documents with embeddings for insertion\n const documents: Array<{\n path: string;\n url: string;\n title: string;\n content: string;\n embedding: number[];\n }> = [];\n \n // Collect pages with embeddings\n const docPrepStart = performance.now();\n for (const page of pages) {\n // Use cached embeddings if available, otherwise generate\n let pageEmbedding = page.embeddings;\n if (!pageEmbedding) {\n // Generate embedding if not cached (should be cached from recalculate, but handle missing)\n pageEmbedding = await generateEmbeddings(page.content);\n if (!pageEmbedding || pageEmbedding.length !== embeddingDimension) {\n continue; // Skip pages without embeddings or wrong dimension\n }\n }\n \n // Ensure embedding dimension matches\n if (pageEmbedding.length !== embeddingDimension) {\n continue;\n }\n \n documents.push({\n path: page.path,\n url: page.url,\n title: page.title || page.path,\n content: page.content,\n embedding: pageEmbedding,\n });\n }\n if (enableTiming) timings.docPrep = performance.now() - docPrepStart;\n \n // Insert all documents into Orama\n const insertStart = performance.now();\n if (documents.length > 0) {\n await insertMultiple(db, documents);\n } else {\n return []; // No documents to search\n }\n if (enableTiming) timings.insert = performance.now() - insertStart;\n \n // Perform vector similarity search using Orama\n const searchStart = performance.now();\n const searchResults = await search(db, {\n mode: \"vector\",\n vector: {\n value: queryEmbedding,\n property: \"embedding\",\n },\n similarity: minSimilarity,\n limit,\n includeVectors: false, // Don't need vectors in response\n });\n if (enableTiming) timings.search = performance.now() - searchStart;\n \n // Transform Orama results to SearchResult format\n const transformStart = performance.now();\n const results: SearchResult[] = searchResults.hits.map((hit: any) => {\n const page = pages.find(p => p.path === hit.document.path);\n const queryWords = query.toLowerCase().split(/\\s+/).filter(w => w.length > 0);\n \n return {\n path: hit.document.path,\n url: hit.document.url,\n title: hit.document.title,\n score: (hit.score || 0) * 100, // Convert similarity to score (0-100)\n snippet: page ? generateSnippet(page.content, queryWords, query.toLowerCase()) : hit.document.content.substring(0, 200) + '...',\n metadata: {\n strategy: \"jigsawstack-orama\",\n similarity: hit.score,\n ...(enableTiming && { timings }),\n },\n };\n });\n if (enableTiming) timings.transform = performance.now() - transformStart;\n \n if (enableTiming) {\n timings.total = performance.now() - startTime;\n console.log(` ⏱️ Timing breakdown:`);\n console.log(` Query embedding: ${timings.queryEmbedding?.toFixed(2)}ms (API call - main bottleneck)`);\n console.log(` DB create: ${timings.dbCreate?.toFixed(2)}ms`);\n console.log(` Doc prep: ${timings.docPrep?.toFixed(2)}ms`);\n console.log(` Insert: ${timings.insert?.toFixed(2)}ms`);\n console.log(` Search: ${timings.search?.toFixed(2)}ms`);\n console.log(` Transform: ${timings.transform?.toFixed(2)}ms`);\n console.log(` Total: ${timings.total?.toFixed(2)}ms`);\n }\n \n return results;\n },\n};\n\n",[],[223,397],"31712298-b901-11f0-878c-0224a6c84d84","index.ts","3171232e-b901-11f0-878c-0224a6c84d84",35,["D",1762207522385],"// Search - Main entry point\n// To switch strategies, comment/uncomment the imports and function calls below\n\nexport * from \"./types.ts\";\nexport * from \"./utils.ts\";\n\nimport type { Page, SearchOptions, SearchResult } from \"./types.ts\";\n// import { searchStrategy, generateEmbeddings } from \"./placeholder.ts\";\n// import { searchStrategy, generateEmbeddings } from \"./jigsawstack-orama.ts\"; // ~550ms query embeddings (API)\n// import { searchStrategy, generateEmbeddings } from \"./openai-orama.ts\"; // ~100-200ms query embeddings (API), ~29ms DB overhead\n// import { searchStrategy, generateEmbeddings } from \"./transformers-cosine.ts\"; // ~10-30ms (browser only), requires --allow-ffi in Deno\nimport { searchStrategy, generateEmbeddings } from \"./openai-cosine.ts\"; // ~100-200ms query embeddings (API), <1ms cosine calc\n\n// Main search function - comment/uncomment imports above to switch strategies\nexport const searchPages = async (\n query: string,\n pages: Page[],\n options: SearchOptions = {}\n): Promise => {\n return searchStrategy.search(query, pages, options);\n};\n\n// Export search strategy for introspection (e.g., /search/test endpoint)\nexport { searchStrategy };\n\n// Embeddings function for recalculate - uses same import as search strategy\nexport const getActiveEmbeddingsFunction = (): ((content: string) => Promise) => {\n return generateEmbeddings;\n};\n\n\n",[],[223,405],"7f271a00-b9ca-11f0-8b68-0224a6c84d84","onnx","7f271ab4-b9ca-11f0-8b68-0224a6c84d84","7f049ff2-b9ca-11f0-98dd-0224a6c84d84",52,["D",1762293981620],[],[223,420,421,413],"models","all-MiniLM-L6-v2","7f049f52-b9ca-11f0-98dd-0224a6c84d84","7eec2a9e-b9ca-11f0-8b68-0224a6c84d84",51,["D",1762293981385],[259],[223,420,421],"7eec29cc-b9ca-11f0-8b68-0224a6c84d84",50,["D",1762293981234],[258],[223,420],["D",1762207521254],[257,260,261,262,263,264,265,266,267],[223],["D",1762207521817],[],[229],"7f537686-b9ca-11f0-8b68-0224a6c84d84","7f537758-b9ca-11f0-8b68-0224a6c84d84",55,["D",1762293981908],"// Answer strategy utilities\n\nimport type { Page } from \"../search/types.ts\";\n\n// Calculate approximate token count (rough estimate: 1 token ≈ 4 characters)\nexport const estimateTokens = (text: string): number => {\n return Math.ceil(text.length / 4);\n};\n\n// Truncate content to fit within token limit\nexport const truncateToTokenLimit = (content: string, maxTokens: number): string => {\n const maxChars = maxTokens * 4;\n if (content.length <= maxChars) {\n return content;\n }\n return content.substring(0, maxChars) + \"\\n...(truncated)\";\n};\n\n// Format pages into context for LLM\nexport const formatPagesAsContext = (\n pages: Page[],\n maxPages?: number,\n maxTokensPerPage?: number\n): { context: string; pagesUsed: number; totalTokens: number } => {\n const pagesToUse = maxPages ? pages.slice(0, maxPages) : pages;\n \n let context = \"\";\n let totalTokens = 0;\n \n for (const page of pagesToUse) {\n let pageContent = page.content;\n \n // Truncate individual page content if needed\n if (maxTokensPerPage) {\n pageContent = truncateToTokenLimit(pageContent, maxTokensPerPage);\n }\n \n const pageTokens = estimateTokens(pageContent);\n totalTokens += pageTokens;\n \n context += `\\n\\n---\\n`;\n context += `Source: ${page.title || page.path}\\n`;\n context += `URL: ${page.url}\\n`;\n context += `---\\n\\n`;\n context += pageContent;\n }\n \n return {\n context,\n pagesUsed: pagesToUse.length,\n totalTokens,\n };\n};\n\n// Default system prompt for documentation Q&A\nexport const DEFAULT_SYSTEM_PROMPT = `You are a helpful AI assistant that answers questions about Groq's documentation.\n\nYou will be provided with relevant documentation pages as context. Use this context to provide accurate, helpful answers to user questions.\n\nGuidelines:\n- Base your answers on the provided documentation context\n- If the answer isn't in the context, say so politely\n- Be concise but thorough\n- Include relevant code examples when available in the context\n- Reference specific documentation sections when helpful\n- Format your response in markdown\n- If multiple approaches are mentioned in the docs, present them clearly\n- When linking to documentation, remove the .md extension from URLs (e.g., use /docs/api-reference instead of /docs/api-reference.md)\n- Use the exact URLs provided in the context, but without .md extensions\n\nRemember: You are answering questions specifically about Groq's API, models, and services based on their official documentation.`;\n\n// Post-process answer to clean up any .md extensions in URLs\nexport const cleanupMarkdownLinks = (answer: string): string => {\n // Remove .md from markdown links: [text](url.md) -> [text](url)\n // Handles various cases:\n // - [text](url.md) -> [text](url)\n // - [text](url.md#anchor) -> [text](url#anchor)\n // - [text](url.md?query) -> [text](url?query)\n return answer.replace(/(\\[[^\\]]+\\]\$[^)]+)\\.md(\$|#|\\?)/g, '$1$2');\n};\n\n",[],[235,139],"7f483adc-b9ca-11f0-b7be-0224a6c84d84","STRATEGY-COMPARISON.md","7f483b86-b9ca-11f0-b7be-0224a6c84d84",54,["D",1762293981801],"# Answer Strategy Comparison\n\nThis document helps you choose the right answer strategy for your use case.\n\n## Current Strategies\n\n### 1. llama-3.3-70b-default ✅ (Active)\n\n**Best for**: General-purpose Q&A, complex questions, high-quality answers\n\n**Configuration**:\n- Model: `llama-3.3-70b-versatile`\n- Max context pages: 5\n- Temperature: 0.3\n- Tokens per page: ~2000\n\n**Performance**:\n- Search: 50-500ms (depends on search strategy)\n- Context prep: <50ms\n- LLM call: 500-3000ms\n- **Total: ~1-3.5s**\n\n**Quality**: ⭐⭐⭐⭐⭐ (5/5)\n**Speed**: ⭐⭐⭐ (3/5)\n**Cost**: ⭐⭐⭐ (3/5)\n\n**Pros**:\n- ✅ Excellent reasoning and comprehension\n- ✅ Handles complex multi-part questions\n- ✅ Good at code examples and technical details\n- ✅ Consistent, reliable answers\n\n**Cons**:\n- ❌ Slower than 8B models\n- ❌ More expensive per token\n- ❌ May be overkill for simple questions\n\n**Use cases**:\n- Complex how-to questions\n- Multi-step implementations\n- Comparing features/models\n- Debugging and troubleshooting\n- Code generation with explanations\n\n---\n\n## Future Strategies (Templates)\n\n### 2. llama-3.1-8b-fast (Not yet implemented)\n\n**Best for**: Simple factual questions, quick lookups, high-volume traffic\n\n**Configuration**:\n- Model: `llama-3.1-8b-instant`\n- Max context pages: 2-3\n- Temperature: 0.3\n- Tokens per page: ~1000\n\n**Expected Performance**:\n- Search: 50-500ms\n- Context prep: <30ms\n- LLM call: 200-800ms\n- **Total: ~0.3-1.3s**\n\n**Quality**: ⭐⭐⭐⭐ (4/5)\n**Speed**: ⭐⭐⭐⭐⭐ (5/5)\n**Cost**: ⭐⭐⭐⭐⭐ (5/5)\n\n**Best for**:\n- \"What models are available?\"\n- \"What is X?\"\n- \"How much does Y cost?\"\n- Simple API lookups\n\n---\n\n### 3. mixtral-8x7b-extended (Not yet implemented)\n\n**Best for**: Very complex questions requiring lots of context\n\n**Configuration**:\n- Model: `mixtral-8x7b-32768`\n- Max context pages: 10\n- Temperature: 0.3\n- Tokens per page: ~3000\n\n**Expected Performance**:\n- Search: 50-500ms\n- Context prep: ~100ms\n- LLM call: 1000-4000ms\n- **Total: ~1.5-5s**\n\n**Quality**: ⭐⭐⭐⭐⭐ (5/5)\n**Speed**: ⭐⭐ (2/5)\n**Cost**: ⭐⭐ (2/5)\n\n**Best for**:\n- \"Compare all available models\"\n- \"How do I implement a complete chat system with X, Y, Z features?\"\n- Questions requiring synthesis across many docs\n\n---\n\n### 4. llama-3.3-70b-code (Not yet implemented)\n\n**Best for**: Code generation and technical implementation questions\n\n**Configuration**:\n- Model: `llama-3.3-70b-versatile`\n- Max context pages: 5\n- Temperature: 0.2 (more deterministic for code)\n- Custom system prompt optimized for code\n\n**Expected Performance**:\n- Similar to llama-3.3-70b-default\n- **Total: ~1-3.5s**\n\n**Quality**: ⭐⭐⭐⭐⭐ (5/5) for code\n**Speed**: ⭐⭐⭐ (3/5)\n**Cost**: ⭐⭐⭐ (3/5)\n\n**Best for**:\n- \"Show me example code for X\"\n- \"How do I implement Y in Python/JavaScript?\"\n- API usage examples\n- Debugging code issues\n\n---\n\n### 5. citation-mode (Not yet implemented)\n\n**Best for**: Academic/research use, when you need to cite sources\n\n**Configuration**:\n- Model: `llama-3.3-70b-versatile`\n- Max context pages: 5\n- Temperature: 0.3\n- Custom system prompt for citations\n- Post-processing to add inline citations\n\n**Expected Performance**:\n- Similar to llama-3.3-70b-default\n- +50-100ms for citation processing\n- **Total: ~1.5-4s**\n\n**Quality**: ⭐⭐⭐⭐⭐ (5/5)\n**Speed**: ⭐⭐⭐ (3/5)\n**Cost**: ⭐⭐⭐ (3/5)\n\n**Best for**:\n- Documentation generation\n- Training materials\n- When you need exact source references\n- Verifying information\n\n---\n\n## Comparison Matrix\n\n| Strategy | Speed | Quality | Cost | Context | Best For |\n|----------|-------|---------|------|---------|----------|\n| **llama-3.3-70b-default** ✅ | Medium | Excellent | Medium | 5 pages | General purpose, complex Q&A |\n| llama-3.1-8b-fast | Fast | Good | Low | 2-3 pages | Simple lookups, high volume |\n| mixtral-8x7b-extended | Slow | Excellent | High | 10 pages | Very complex questions |\n| llama-3.3-70b-code | Medium | Excellent | Medium | 5 pages | Code generation |\n| citation-mode | Medium | Excellent | Medium | 5 pages | Research, documentation |\n\n## Choosing a Strategy\n\n### Decision Tree\n\n1. **Is the question simple and factual?**\n - Yes → Use `llama-3.1-8b-fast` (when implemented)\n - No → Continue\n\n2. **Does it require lots of documentation context?**\n - Yes → Use `mixtral-8x7b-extended` (when implemented)\n - No → Continue\n\n3. **Is it primarily about code/implementation?**\n - Yes → Use `llama-3.3-70b-code` (when implemented)\n - No → Continue\n\n4. **Do you need citations?**\n - Yes → Use `citation-mode` (when implemented)\n - No → Use `llama-3.3-70b-default` ✅\n\n### By Question Type\n\n**Factual Questions** (\"What is X?\")\n- 🥇 llama-3.1-8b-fast (fast + good enough)\n- 🥈 llama-3.3-70b-default (better quality)\n\n**How-To Questions** (\"How do I X?\")\n- 🥇 llama-3.3-70b-default (balanced)\n- 🥈 llama-3.3-70b-code (if code-heavy)\n\n**Complex Questions** (\"How do I build X with Y and Z?\")\n- 🥇 mixtral-8x7b-extended (more context)\n- 🥈 llama-3.3-70b-default (usually sufficient)\n\n**Code Examples** (\"Show me code for X\")\n- 🥇 llama-3.3-70b-code (optimized)\n- 🥈 llama-3.3-70b-default (good enough)\n\n**Comparison Questions** (\"What's the difference between X and Y?\")\n- 🥇 llama-3.3-70b-default (good reasoning)\n- 🥈 mixtral-8x7b-extended (if comparing many things)\n\n### By Performance Requirements\n\n**Need fastest response** (<1s goal)\n- Use `llama-3.1-8b-fast` (when implemented)\n- Reduce `maxContextPages` to 2\n- Use fastest search strategy\n\n**Need best quality** (no time constraint)\n- Use `mixtral-8x7b-extended` (when implemented)\n- Increase `maxContextPages` to 10\n- Raise `minScore` to 60+\n\n**Balanced** (1-3s acceptable)\n- Use `llama-3.3-70b-default` ✅ (current default)\n- Default settings work well\n\n### By Traffic Patterns\n\n**High volume, many simple questions**\n- Implement and use `llama-3.1-8b-fast`\n- Consider caching common answers\n- Use rate limiting\n\n**Low volume, complex questions**\n- Use `llama-3.3-70b-default` or `mixtral-8x7b-extended`\n- Quality over speed\n\n**Mixed traffic**\n- Route simple questions to fast strategy\n- Route complex questions to powerful strategy\n- Consider implementing multi-strategy endpoint\n\n## Cost Considerations\n\nApproximate token costs per answer (based on Groq pricing):\n\n### llama-3.3-70b-default\n- Context: ~10k tokens (5 pages × 2k each)\n- Answer: ~500 tokens\n- **Total: ~10.5k tokens per answer**\n\n### llama-3.1-8b-fast (estimated)\n- Context: ~3k tokens (3 pages × 1k each)\n- Answer: ~300 tokens\n- **Total: ~3.3k tokens per answer**\n- **~3x cheaper than 70B**\n\n### mixtral-8x7b-extended (estimated)\n- Context: ~30k tokens (10 pages × 3k each)\n- Answer: ~700 tokens\n- **Total: ~30.7k tokens per answer**\n- **~3x more expensive than default**\n\n### Cost-saving strategies:\n1. Use smaller models for simple questions\n2. Reduce `maxContextPages`\n3. Increase `minScore` (fewer pages in context)\n4. Cache common questions/answers\n5. Implement tiered routing\n\n## Implementation Guide\n\n### Adding a New Strategy\n\n1. **Copy template**:\n ```bash\n cp answer/llama-3.3-70b-default.ts answer/my-strategy.ts\n ```\n\n2. **Modify configuration**:\n ```typescript\n const DEFAULT_MODEL = \"your-model\";\n const DEFAULT_MAX_CONTEXT_PAGES = 3;\n const DEFAULT_TEMPERATURE = 0.5;\n ```\n\n3. **Update strategy metadata**:\n ```typescript\n export const answerStrategy: AnswerStrategy = {\n name: \"my-strategy\",\n description: \"What makes it special\",\n answer: async (query, options) => { /* ... */ }\n };\n ```\n\n4. **Activate**:\n ```typescript\n // answer/index.ts\n import { answerStrategy } from \"./my-strategy.ts\";\n ```\n\n5. **Test**:\n ```bash\n curl \"http://localhost:8000/answer/info\"\n curl \"http://localhost:8000/answer?q=test\"\n ```\n\n### Testing Multiple Strategies\n\nCreate a comparison test script:\n\n```typescript\n// testing/answer-comparison.ts\nimport { questions } from \"./questions.ts\";\n\nconst strategies = [\n \"llama-3.3-70b-default\",\n \"llama-3.1-8b-fast\",\n \"mixtral-8x7b-extended\"\n];\n\nfor (const strategy of strategies) {\n for (const question of questions) {\n // Switch strategy\n // Run question\n // Collect metrics\n }\n}\n// Compare results\n```\n\n## Monitoring and Optimization\n\n### Key Metrics to Track\n\n1. **Response time breakdown**:\n - Search duration\n - Context prep duration\n - LLM duration\n - Total duration\n\n2. **Quality metrics**:\n - User feedback/ratings\n - Answer correctness\n - Relevance of sources\n\n3. **Cost metrics**:\n - Tokens per answer\n - Cost per answer\n - Monthly spend\n\n4. **Usage patterns**:\n - Question types\n - Model distribution\n - Cache hit rates\n\n### Optimization Tips\n\n1. **Speed**: \n - Profile with `enableTiming: true`\n - Optimize slowest component\n - Consider caching\n\n2. **Quality**:\n - Test with real questions\n - Tune system prompts\n - Adjust context size\n\n3. **Cost**:\n - Route by question complexity\n - Cache common answers\n - Use smaller models when possible\n\n## Future Enhancements\n\n### Multi-Strategy Routing\n\nAutomatically select strategy based on question analysis:\n\n```typescript\nasync function smartRoute(question: string) {\n const complexity = analyzeComplexity(question);\n const type = classifyQuestion(question);\n \n if (complexity === \"simple\" && type === \"factual\") {\n return \"llama-3.1-8b-fast\";\n } else if (type === \"code\") {\n return \"llama-3.3-70b-code\";\n } else if (complexity === \"complex\") {\n return \"mixtral-8x7b-extended\";\n }\n return \"llama-3.3-70b-default\";\n}\n```\n\n### Answer Caching\n\nCache answers for common questions:\n\n```typescript\nconst cachedAnswer = await cache.get(questionHash);\nif (cachedAnswer) return cachedAnswer;\n\nconst answer = await generateAnswer(question);\nawait cache.set(questionHash, answer, ttl);\n```\n\n### Follow-up Questions\n\nSupport conversation context:\n\n```typescript\nawait answerQuestion(question, {\n conversationHistory: previousQA,\n maxContextPages: 3 // Reduced to fit history\n});\n```\n\n## Resources\n\n- **Groq Models**: https://console.groq.com/docs/models\n- **Groq Pricing**: https://groq.com/pricing/\n- **Model Benchmarks**: https://console.groq.com/docs/benchmarks\n\n",[],[235,447],"7f58d5d6-b9ca-11f0-afaf-0224a6c84d84",["D",1762293981932],[],[235,32],"7f40d292-b9ca-11f0-8b68-0224a6c84d84",".gitkeep","7f40d350-b9ca-11f0-8b68-0224a6c84d84",53,["D",1762293981787],"# Answer Strategies Directory\n\nThis folder contains RAG (Retrieval-Augmented Generation) strategies for answering questions about Groq documentation.\n\nSee README.md and QUICK-START.md for documentation.\n\n",[],[235,459],["D",1762293980863],[251,252,253,254],[235],["D",1746217442601],{"_94":93,"_101":97},{"_94":93,"_95":-5,"_96":97,"_18":53,"_98":99,"_100":24},{"_13":83,"_31":84,"_41":40,"_85":42,"_86":-5,"_87":-5,"_88":-5,"_89":-5,"_90":-5,"_91":43,"_92":93},"ctx",{"_76":-5,"_121":506,"_507":508,"_509":510,"_511":24,"_512":24,"_513":24,"_514":47,"_515":-5,"_516":-7,"_517":-7,"_518":60,"_519":24,"_520":24,"_521":-5,"_522":24,"_523":24,"_524":24,"_525":-5},"ENV",{"_477":478,"_479":480,"_481":84,"_482":483,"_484":485,"_486":487,"_488":489,"_490":491,"_492":493,"_494":495,"_496":497,"_498":499,"_500":501,"_502":503,"_504":505},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v56