feat: implement search with ✨jAI (#202)

## Description
<!-- Please add PR description (don't leave blank) - example: This PR
[adds/removes/fixes/replaces] the [feature/bug/etc] -->

This pull request introduces a new "Search with ✨jAI" feature to the
word search experience; before this, whenever a word was searched and it
didn't exist in the dictionary, we'd get a `No Result Found` feedback,
but now we get this options replacing the no found with search for the
word with ✨jAI.

This feature enable us route to a page where the meaning to that word is
generated on the fly using ✨jAI.

### Notable Changes

**1. AI-powered word definitions and prompt improvements**
- Added a new dedicated prompt template (`SEARCH_WORD`) in
`jai-prompts.js` for generating structured, SEO-friendly definitions,
and moved the original personality prompt to this file.
(`apps/jai/lib/jai-prompts.js`, `apps/jai/lib/jai-prompt.js` removed,
`apps/jai/index.js`, `apps/jai/README.md`)
[[1]](diffhunk://#diff-815b78cdf6ccc854f55ec0c701767e3969f07ce877749fb919892873cdc28712R1-R74)
[[2]](diffhunk://#diff-82c094682b612a0966e5684b3ad170b5814750d54ff6d0c8be39f8aa6d2f52ecL1-L36)
[[3]](diffhunk://#diff-5439cc07d5881e2e44a6e29b3126ebe43820b54254eca7a57282cf3bca01b122L3-R6)
[[4]](diffhunk://#diff-b9fdf9d9f9a7a0c8030ced20f610c30cf1ddddb9918ea834e387e3e6f5e8adf6L52-R65)
- Updated documentation to describe the new AI-powered word definition
feature and explain the structure and style of generated definitions.
(`apps/jai/README.md`)
[[1]](diffhunk://#diff-b9fdf9d9f9a7a0c8030ced20f610c30cf1ddddb9918ea834e387e3e6f5e8adf6R15)
[[2]](diffhunk://#diff-b9fdf9d9f9a7a0c8030ced20f610c30cf1ddddb9918ea834e387e3e6f5e8adf6L52-R65)

**2. New React UI components for ✨jAI integration**
- Added `logo.jsx`, a reusable SVG React component for ✨jAI branding.
(`apps/jai/components/logo.jsx`)
- Added `word-search.jsx`, a React component for generating and
displaying AI-powered word definitions, including error handling,
loading states, and a trigger component for UI integration.
(`apps/jai/components/word-search.jsx`)
- Integrated the `JAIWordSearchTrigger` into the main search UI for easy
access to AI-powered definitions. (`src/components/islands/search.jsx`)

**3. Documentation and architecture updates**
- Expanded the `README.md` to clarify the module structure, document new
components, and explain the updated integration flow, including the new
`/api/jai/search` endpoint. (`apps/jai/README.md`)
[[1]](diffhunk://#diff-b9fdf9d9f9a7a0c8030ced20f610c30cf1ddddb9918ea834e387e3e6f5e8adf6R36-R40)
[[2]](diffhunk://#diff-b9fdf9d9f9a7a0c8030ced20f610c30cf1ddddb9918ea834e387e3e6f5e8adf6R87-R108)
[[3]](diffhunk://#diff-b9fdf9d9f9a7a0c8030ced20f610c30cf1ddddb9918ea834e387e3e6f5e8adf6L114-R159)

**4. Model selection and configuration**
- Changed the default OpenAI chat model to `gpt-4.1-mini` for both local
development (`.env.example`) and documentation, and added detailed notes
about model selection strategy for different ✨jAI features.
(`.env.example`, `apps/jai/lib/model.js`, `apps/jai/README.md`)
[[1]](diffhunk://#diff-a3046da0d15a27e89f2afe639b25748a7ad4d9290af3e7b1b6c1a5533c8f0a8cL16-R16)
[[2]](diffhunk://#diff-f74c575d26128dd8394213eb0a7cdb8be7e0618fba3bfc1254ac1dbcf3c3942eR1-R29)
[[3]](diffhunk://#diff-b9fdf9d9f9a7a0c8030ced20f610c30cf1ddddb9918ea834e387e3e6f5e8adf6R87-R108)

**5. Minor cleanups**
- Removed unused or problematic files from `.prettierignore` to reduce
noise in formatting tools. (`.prettierignore`)

These changes collectively enhance the user experience, developer
clarity, and the overall flexibility of the `apps/jai` module for future
features and scaling.

## Related Issue
<!-- Please prefix the issue number with Fixes/Resolves - example: Fixes
#123 or Resolves #123 -->

Fixes jargonsdev/roadmap#8

## Screenshots/Screencasts
<!-- Please provide screenshots or video recording that demos your
changes (especially if it's a visual change) -->

[screen-capture
(5).webm](https://github.com/user-attachments/assets/ff67fd8d-1d3f-4ab3-bbea-04588228dfb8)

### Search for word that a not technical term or not related to
software, programming ec. fields

<img width="1128" height="671" alt="image"
src="https://github.com/user-attachments/assets/ab943964-ce0f-4ed8-a4fd-bdbf0cb5b16d"
/>

## Notes to Reviewer
<!-- Please state here if you added a new npm packages, or any extra
information that can help reviewer better review you changes -->

- Confirm presence of the ✨jAI related environmental variables for this
to work in production

Author: babblebey

.env.example

@@ -13,7 +13,7 @@ PUBLIC_PROJECT_REPO_BRANCH_REF="refs/heads/main"
 
 # LLM and Embedding Model - Optional to run jAI locally - Get keys https://platform.openai.com
 OPENAI_API_KEY=sk-proj-*************************************
-OPENAI_CHAT_MODEL=gpt-4.1
+OPENAI_CHAT_MODEL=gpt-4.1-mini
 OPENAI_EMBEDDINGS_MODEL=text-embedding-3-small
 
 # Vector Store - Optional to run jAI locally - Get Keys https://qdrant.tech

.prettierignore

@@ -31,9 +31,6 @@ package-lock.json
 .DS_Store
 Thumbs.db
 
-# SVG files with CDATA that cause parsing issues
-src/components/jargonsdev-logo.astro
-
 # Files with parsing issues in inline scripts
 src/layouts/base.astro
 

apps/jai/README.md

@@ -12,6 +12,7 @@
 
 Unlike standalone AI applications, ✨jAI is deeply integrated into the jargons.dev ecosystem, powering features like:
 
+- **AI-powered word definitions**: Generate instant definitions for technical terms not yet in the dictionary
 - Intelligent word explanations and follow-up conversations
 - Semantic search across the dictionary
 - Context-aware responses based on the curated dictionary content
@@ -31,9 +32,12 @@ The ✨jAI module is organized into focused utility files:
 
 ```
 apps/jai/
-├── index.js              # Main exports and module interface
+├── index.js               # Main exports and module interface
+├── components/            # React components for UI/feature integration
+│   ├── logo.jsx           # jAI Logo
+│   └── word-search.jsx    # jAI Word Search feature
 └── lib/
-    ├── jai-prompt.js      # AI personality and prompt templates
+    ├── jai-prompts.js      # AI personality and prompt templates
     ├── model.js           # OpenAI model configuration
     ├── utils.js           # Utility functions for message formatting
     └── vector-store.js    # Qdrant vector store integration
@@ -49,14 +53,16 @@ Main module interface that exports all ✨jAI utilities:
 export { jAIPrompt, formatMessage, model, vectorStore };
 ```
 
-#### `lib/jai-prompt.js`
+#### `lib/jai-prompts.js`
 
 Defines ✨jAI's personality and conversation templates. The AI assistant is designed to:
 
 - Explain technical jargon clearly and concisely
 - Use relatable analogies and developer-friendly examples
 - Maintain a friendly, witty personality
 - Encourage follow-up questions and deeper exploration
+- Generate accurate, SEO-friendly definitions for technical terms
+- Provide structured responses optimized for dictionary content
 
 #### `lib/model.js`
 
@@ -78,14 +84,28 @@ Manages the Qdrant vector database integration:
 
 Utility functions for message processing and formatting.
 
+#### `components/logo.jsx`
+
+SVG React component for the ✨jAI logo with customizable styling. Used throughout the application for branding and visual identity.
+
+#### `components/word-search.jsx`
+
+React component that powers the AI-driven word definition feature. Includes:
+
+- **JAIWordSearch**: Main component for generating and displaying AI-powered word definitions
+- **JAIWordSearchTrigger**: UI trigger component for initiating word searches with ✨jAI
+- Streaming response handling for real-time definition generation
+- Error handling and loading states
+- Integration with the `/api/jai/search` endpoint
+
 ## Environment Variables
 
 ✨jAI requires the following environment variables:
 
 ```bash
 # OpenAI Configuration
 OPENAI_API_KEY=your_openai_api_key
-OPENAI_CHAT_MODEL=gpt-4-turbo-preview  # or your preferred model
+OPENAI_CHAT_MODEL=gpt-4.1-mini  # or your preferred model
 OPENAI_EMBEDDINGS_MODEL=text-embedding-3-small
 
 # Qdrant Vector Database
@@ -111,22 +131,32 @@ This command processes all dictionary entries and creates embeddings for semanti
 
 ## Architecture Integration
 
-✨jAI is designed as a utility module that integrates seamlessly with the main jargons.dev application. The module is consumed in two primary areas:
+✨jAI is designed as a utility module that integrates seamlessly with the main jargons.dev application. The module is consumed in three primary areas:
 
 ### 1. Vector Store Seeding (`dev/seed-vector-store.js`)
 
 Uses the `vectorStore` utility to populate the database with dictionary content. The script fetches dictionary entries from the jargons.dev API, processes them into document chunks, and creates vector embeddings for semantic search capabilities.
 
-### 2. API Endpoint (`src/pages/api/jai/follow-up-chat.js`)
+### 2. Word Search API (`src/pages/api/jai/search.js`)
+
+Dedicated endpoint for AI-powered word definitions that:
+
+- Uses the `SEARCH_WORD` prompt template for structured, dictionary-optimized responses
+- Streams AI-generated definitions in real-time
+- Provides fallback definitions for terms not yet in the dictionary
+- Powers the `/browse/with-jai` page and word search components
+
+<!-- ### 3. Follow-up Chat API (`src/pages/api/jai/follow-up-chat.js`)
 
-Imports all four core utilities (`jAIPrompt`, `model`, `formatMessage`, `vectorStore`) for real-time AI interactions. Powers the follow-up chat feature with semantic search for relevant context, conversation history management, and streaming AI response generation.
+Imports all four core utilities (`jAIPrompt`, `model`, `formatMessage`, `vectorStore`) for real-time AI interactions. Powers the follow-up chat feature with semantic search for relevant context, conversation history management, and streaming AI response generation. -->
 
 ### Integration Flow
 
 1. **Data Preparation**: `seed-vector-store.js` populates the vector database with dictionary content
-2. **Runtime Processing**: API endpoints use ✨jAI utilities for semantic search and AI response generation
-3. **Real-time Interaction**: Streaming responses provide immediate feedback to users
-4. **Context Awareness**: Vector search ensures AI responses are grounded in dictionary content
+2. **Word Search Flow**: Users can search for undefined terms via `/browse/with-jai`, which uses the search API to generate instant definitions
+3. **Runtime Processing**: API endpoints use ✨jAI utilities for semantic search and AI response generation
+4. **Real-time Interaction**: Streaming responses provide immediate feedback to users
+5. **Context Awareness**: Vector search ensures AI responses are grounded in dictionary content
 
 ## Development
 

apps/jai/components/logo.jsx

@@ -0,0 +1,40 @@
+export default function JAILogo({ className }) {
+  return (
+    <svg
+      className={className}
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 780 420"
+    >
+      <g>
+        <g>
+          <path
+            className="fill-white"
+            d="M208 65c11,-13 29,-20 47,-15 14,5 26,16 30,31l13 44c1,4 3,7 6,10 3,3 7,6 11,7l44 12c1,1 2,1 3,1 3,-1 7,-2 11,-2l18 0c0,-1 0,-2 0,-4l0 -8c0,-14 5,-27 15,-37 11,-12 27,-15 43,-15 16,0 31,3 42,15 6,5 10,12 13,19 5,-12 17,-20 30,-20l59 0c5,0 9,1 14,3 4,-2 9,-3 14,-3l124 0c18,0 33,15 33,34l0 30c0,19 -15,34 -33,34l-8 0 0 64 8 0c18,0 33,15 33,33l0 31c0,18 -15,33 -33,33l-93 0c-1,0 -3,0 -4,0 -1,0 -2,0 -3,0l-44 0c-16,0 -29,-10 -33,-25l-5 -21 -1 0 -6 21c-3,15 -16,25 -32,25l-24 0c-2,12 -8,24 -17,33 -15,16 -36,22 -57,22l-52 0c-18,0 -34,-15 -34,-33l0 -32c0,-18 16,-33 34,-33l21 0 0 -67 -22 0c-9,0 -17,-4 -24,-10l-34 10c-4,1 -8,3 -11,6 -3,3 -5,7 -6,11l-13 44c-7,23 -31,37 -55,30 -15,-4 -26,-15 -30,-30l0 -1c-6,10 -16,18 -28,20l-15 4c-2,1 -3,1 -4,2 -1,1 -2,2 -2,3 0,1 0,1 0,1l-4 16c-6,23 -30,38 -54,32 -16,-4 -28,-17 -32,-33l-4 -15c0,-2 -1,-3 -2,-4 -1,-1 -2,-1 -4,-2l-15 -4c-24,-6 -39,-30 -33,-54 4,-16 17,-28 33,-32l15 -4c2,0 3,-1 4,-2 1,-1 2,-2 2,-3 0,0 0,-1 0,-2l4 -14c4,-17 18,-30 34,-33 0,-1 1,-2 1,-3 1,-4 3,-7 4,-10 -7,-6 -12,-13 -15,-22l-4 -13 -14 -5c-23,-8 -36,-33 -28,-56 4,-13 15,-24 28,-28l14 -5 4 -13c8,-23 33,-36 56,-28 13,4 24,15 28,28l5 13 13 5c9,3 16,8 21,14zm-30 73l-4 2 -1 1c2,-1 3,-2 5,-3z"
+          />
+          <g>
+            <path
+              id="sparkle.svg"
+              className="fill-black"
+              d="M117 43l-6 18c0,0 0,1 -1,1 -1,4 -3,6 -5,9 -3,3 -6,5 -9,6l-18 6c-4,1 -6,3 -7,7 -2,5 1,11 7,13l18 6c3,2 6,4 9,6 3,3 5,6 6,9l6 19c1,3 3,5 7,6 5,2 11,-1 13,-6l6 -19c2,-3 4,-6 6,-9 3,-2 6,-4 9,-6l19 -6c3,-1 5,-3 7,-7 1,-5 -2,-11 -7,-13l-19 -6c-3,-1 -6,-3 -9,-6 -2,-3 -4,-6 -6,-9l-6 -19c-1,-3 -3,-5 -7,-6 -5,-2 -11,1 -13,6z"
+            />
+            <path
+              id="sparkle.svg_0"
+              className="fill-black"
+              d="M93 229l-3 15c0,1 -1,1 -1,1 -2,7 -5,14 -10,19 -6,5 -12,9 -19,11l-16 4c-4,1 -7,4 -8,8 -2,5 2,11 8,13l16 4c7,2 13,5 19,11 5,5 9,11 10,19l4 15c1,4 4,7 8,8 6,2 12,-2 14,-7l4 -16 0 0 0 0c1,-8 5,-14 10,-19 5,-6 12,-9 19,-11l16 -4c4,-1 7,-4 8,-8 2,-6 -2,-12 -8,-13l-16 -4c-7,-2 -14,-6 -19,-11 -5,-5 -9,-12 -10,-19 0,0 0,0 0,0l-4 -16c-1,-4 -4,-7 -8,-8 -6,-1 -12,2 -14,8z"
+            />
+            <path
+              id="sparkle.svg_1"
+              className="fill-black"
+              d="M643 298l19 0 0 -131 -41 0 0 -30 124 0 0 30 -42 0 0 131 42 0 0 31 -93 0 -9 -31zm-80 -121l-2 0 -19 72 40 0 -19 -72zm38 152l-13 -46 -52 0 -12 46 -42 0 52 -192 59 0 52 192 -44 0zm-227 23l54 0 0 -133 -55 0 0 -32 96 0 0 156c0,12 -3,22 -11,29 -7,8 -18,12 -32,12l-52 0 0 -32zm75 -183c-9,0 -16,-2 -19,-6 -4,-4 -6,-8 -6,-14l0 -8c0,-5 2,-10 6,-13 3,-4 10,-6 19,-6 9,0 15,2 19,6 4,3 5,8 5,13l0 8c0,6 -1,10 -5,14 -4,4 -10,6 -19,6z"
+            />
+            <path
+              id="sparkle.svg_2"
+              className="fill-black"
+              d="M232 90l-12 43c0,1 0,1 0,1 -3,10 -8,18 -15,25 -7,7 -16,12 -26,15l-43 12c-4,1 -7,4 -8,8 -1,6 2,12 8,13l43 13c10,3 19,8 26,15 7,7 12,15 15,25l12 44c1,3 4,6 8,7 5,2 11,-1 13,-7l12 -44c3,-10 8,-18 15,-25 7,-7 16,-12 26,-15l43 -13c4,-1 7,-3 8,-7 1,-6 -2,-12 -8,-14l-43 -12c-10,-3 -19,-8 -26,-15 -7,-7 -12,-15 -15,-25l-12 -44c-1,-3 -4,-6 -8,-7 -5,-2 -11,1 -13,7z"
+            />
+          </g>
+        </g>
+      </g>
+    </svg>
+  );
+}

apps/jai/components/word-search.jsx

@@ -0,0 +1,108 @@
+/**
+ * JAI Word Search Feature Components
+ * @exports JAIWordSearch - Fetches and displays AI-generated word definitions with loading and error states
+ * @exports JAIWordSearchTrigger - Link component to initiate a word search with jAI
+ */
+
+import { useEffect, useState } from "react";
+import Markdown from "react-markdown";
+import { useChat } from "@ai-sdk/react";
+import JAILogo from "./logo.jsx";
+import { capitalizeText } from "../../../src/lib/utils/index.js";
+
+/**
+ * JAI Word Search Component
+ * @param {Object} props
+ * @param {string} props.word - The word to search
+ * @returns {JSX.Element}
+ */
+export default function JAIWordSearch({ word }) {
+  const [error, setError] = useState(null);
+
+  /**
+   * Initialize useChat hook
+   */
+  const { messages, status, append } = useChat({
+    api: "/api/jai/search",
+    onError: (e) => {
+      setError(JSON.parse(e.message));
+      console.error(e);
+    },
+  });
+
+  /**
+   * Handle Asking jAI for the word definition
+   */
+  useEffect(() => {
+    append({
+      role: "user",
+      content: `define ${word}`,
+    });
+  }, [word]);
+
+  /**
+   * Loading State
+   */
+  if (status === "submitted" || (status === "ready" && messages.length === 0))
+    return (
+      <div className="space-y-4">
+        <div className="h-6 w-full animate-pulse bg-gray-200 rounded-md" />
+        <div className="h-6 w-3/4 animate-pulse bg-gray-200 rounded-md" />
+        <div className="h-6 w-4/5 animate-pulse bg-gray-200 rounded-md" />
+        <div className="h-6 w-3/5 animate-pulse bg-gray-200 rounded-md" />
+      </div>
+    );
+
+  /**
+   * Error State
+   */
+  if (error)
+    return (
+      <div className="rounded-md bg-red-50 p-4">
+        <div className="flex items-center gap-2">
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            fill="none"
+            viewBox="0 0 24 24"
+            strokeWidth={1.5}
+            stroke="currentColor"
+            className="size-6 text-red-800"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M12 9v3.75m9-.75a9 9 0 1 1-18 0 9 9 0 0 1 18 0Zm-9 3.75h.008v.008H12v-.008Z"
+            />
+          </svg>
+          <p className="font-medium text-red-800">
+            An Error Occured while generating the definition for{" "}
+            <span className="font-bold">{word}</span>.
+          </p>
+        </div>
+      </div>
+    );
+
+  return messages
+    .filter((msg) => msg.role !== "user")
+    .map((msg, index) => <Markdown key={index}>{msg.content}</Markdown>);
+}
+
+/**
+ * JAI Word Search Trigger Component
+ * @param {Object} props
+ * @param {string} props.word - The word to search
+ * @param {number} props.cursor - The cursor position for keyboard navigation
+ * @returns {JSX.Element}
+ */
+export const JAIWordSearchTrigger = ({ word, cursor }) => (
+  <a
+    href={`/browse/with-jai?word=${word}`}
+    className={`${cursor === 0 && "bg-gray-100 _cursor"} relative flex items-center justify-between no-underline w-full p-2 md:p-4 hover:bg-gray-100`}
+  >
+    <span>{capitalizeText(word)}</span>
+    <span className="absolute right-0 mr-2 md:mr-4 flex items-center gap-2">
+      <span>Search with</span>
+      <JAILogo className="w-11 md:w-14 drop-shadow-md" />
+    </span>
+  </a>
+);

apps/jai/index.js

@@ -1,6 +1,6 @@
 import model from "./lib/model.js";
 import { formatMessage } from "./lib/utils.js";
-import { jAIPrompt } from "./lib/jai-prompt.js";
+import { jAIPrompts } from "./lib/jai-prompts.js";
 import vectorStore from "./lib/vector-store.js";
 
-export { jAIPrompt, formatMessage, model, vectorStore };
+export { jAIPrompts, formatMessage, model, vectorStore };