Merge branch 'main' into main

Author: tarunchy

.github/workflows/pr-validation.yml

@@ -0,0 +1,48 @@
+name: MDX Validation
+
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/**'
+
+jobs:
+  mdx-validation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+          
+      - name: MDX validation dependencies
+        run: npm install --save-dev @mdx-js/mdx @mdx-js/loader glob
+        
+      - name: Validate MDX files
+        run: node scripts/validate-mdx.js
+          
+      - name: Check for broken links
+        run: |
+          # Simple check for common broken link patterns
+          echo "Checking for potential broken links..."
+          if grep -r "http://localhost\|http://127.0.0.1" docs/; then
+            echo "❌ Found localhost links that should be removed"
+            exit 1
+          fi
+          echo "✅ No obvious broken links found"
+          
+      - name: Validate frontmatter
+        run: |
+          # Check that all MDX files have required frontmatter
+          find docs -name "*.mdx" -type f | while read file; do
+            if ! head -n 10 "$file" | grep -q "^---$"; then
+              echo "❌ $file - Missing frontmatter (no --- markers)"
+              exit 1
+            fi
+            echo "✅ $file - Has frontmatter"
+          done 

docs/showcase/briefo.mdx

@@ -0,0 +1,64 @@
+---
+title: Briefo | Perplexity Powered News & Finance Social App
+description: AI curated newsfeed, social discussion, and deep research reports built on the Sonar API
+sidebar_position: 1
+keywords: [Briefo, finance, news, social media, React Native, Supabase]
+---
+
+# Briefo | Perplexity Powered News & Finance Social App
+
+**Briefo** delivers a personalized, AI generated newsfeed and company deep dives. Readers can follow breaking stories, request on demand financial analyses, and discuss insights with friends, all in one mobile experience powered by Perplexity’s Sonar API.
+
+## Features
+
+* Personalized newsfeed across 17 categories with AI summaries and source links  
+* Private and public threads for article discussion and sharing  
+* Watch list with real time market snapshots and optional AI analyses  
+* Deep research reports generated on 12 selectable criteria such as management, competitors, and valuation  
+* General purpose chat assistant that remembers each user’s preferred topics  
+
+## Prerequisites
+
+* Node 18 LTS or newer  
+* npm, Yarn, or pnpm  
+* Expo CLI (`npm i -g expo-cli`)  
+* Supabase CLI 1.0 or newer for local emulation and Edge Function deploys  
+
+## Installation
+
+git clone https://github.com/adamblackman/briefo-public.git
+cd briefo-public
+npm install
+### Environment variables
+
+# .env              (project root)
+MY_SUPABASE_URL=https://<project>.supabase.co
+MY_SUPABASE_SERVICE_ROLE_KEY=...
+PERPLEXITY_API_KEY=...
+LINKPREVIEW_API_KEY=...
+ALPACA_API_KEY=...
+ALPACA_SECRET_KEY=...
+
+# .env.local        (inside supabase/)
+# duplicate or override any secrets needed by Edge Functions
+
+## Usage
+Run the Expo development server:
+
+npx expo start
+
+Deploy Edge Functions when you are ready:
+
+supabase functions deploy perplexity-news perplexity-chat perplexity-research portfolio-tab-data
+
+## Code Explanation
+
+* Frontend: React Native with Expo Router (TypeScript) targeting iOS, Android, and Web
+* Backend: Supabase (PostgreSQL, Row Level Security, Realtime) for data and authentication
+* Edge Functions: TypeScript on Deno calling Perplexity, Alpaca, Alpha Vantage, and LinkPreview APIs
+* Hooks: Reusable React Query style data hooks live in lib/ and hooks/
+* Testing and Linting: ESLint, Prettier, and Expo Lint maintain code quality
+
+## Links
+https://github.com/adamblackman/briefo-public
+https://www.briefo.fun/

docs/showcase/citypulse-ai-search.mdx

@@ -0,0 +1,63 @@
+---
+title: CityPulse - AI-Powered Geospatial Discovery Search
+description: Real-time local discovery search using Perplexity AI for personalized location insights and recommendations
+sidebar_position: 2
+keywords: [perplexity, geospatial, location, real-time, maps, local-discovery, sonar]
+---
+
+# CityPulse - AI-Powered Geospatial Discovery
+
+![CityPulse Main Interface](https://raw.githubusercontent.com/anevsky/CityPulse/main/assets/CityPulse-GeoSearch-App-1.jpg)
+
+CityPulse is an intelligent location-based discovery search that helps users explore what's happening around them right now. It demonstrates how to create personalized, real-time local insights using Perplexity's Sonar models.
+
+[![Demo Video](https://cdn.loom.com/sessions/thumbnails/6507fa27571442e680edf787b0f0690d-2fa2c36169822631-full-play.gif)](https://youtu.be/Y0UIhh3diJg)
+
+## What CityPulse Does
+
+- **Real-time local discovery** - Find current events, restaurants, and local alerts near any location
+- **AI-powered search suggestions** - Get intelligent search recommendations as you type
+- **Personalized insights** - Receive AI-generated advice on what to try, best times to visit, and pro tips
+- **Interactive mapping** - Explore results on an interactive map with custom markers and detailed popups
+
+![Search Interface](https://raw.githubusercontent.com/anevsky/CityPulse/main/assets/CityPulse-GeoSearch-App-2.jpg)
+
+## How It Uses Perplexity Sonar
+
+CityPulse leverages two key Perplexity models:
+
+**Sonar for Real-Time Data**
+```python
+# Get current local information with geographic context
+response = client.chat.completions.create(
+    model="sonar",
+    messages=[{
+        "role": "user", 
+        "content": f"Find current events, restaurants, and alerts near {lat}, {lng}"
+    }],
+    response_format={"type": "json_schema", "json_schema": {"schema": LOCAL_INFO_SCHEMA}}
+)
+```
+
+**Sonar Reasoning for Personalized Insights**
+```python
+# Generate AI-powered location recommendations
+response = client.chat.completions.create(
+    model="sonar-reasoning",
+    messages=[{
+        "role": "user",
+        "content": f"Provide personalized insights for {location_name}: what to try, best times to visit, pro tips"
+    }]
+)
+```
+
+The app uses structured JSON schemas to ensure consistent data formatting and includes citation tracking for source verification.
+
+![AI Insights](https://raw.githubusercontent.com/anevsky/CityPulse/main/assets/CityPulse-GeoSearch-App-3.jpg)
+
+## Links
+
+- [GitHub Repository](https://github.com/anevsky/CityPulse)
+- [Live Demo](https://citypulse-ppx.uc.r.appspot.com/)
+- [Video Demo](https://youtu.be/Y0UIhh3diJg)
+- **[Built with ❤️ by Alex Nevsky](https://alexnevsky.com)**

docs/showcase/fact-dynamics.mdx

@@ -0,0 +1,105 @@
+---
+title: Fact Dynamics | Real-time Fact-Checking Flutter App
+description: Cross-platform app for real-time fact-checking of debates, speeches, and images using Perplexity's Sonar API
+sidebar_position: 3
+keywords: [Fact Dynamics, fact-checking, Flutter, Dart, real-time, speech-to-text, debate, image verification]
+---
+
+# Fact Dynamics | Real-time Fact-Checking Flutter App
+<p align="center">
+  <img
+    src="https://raw.githubusercontent.com/vishnu32510/fact_pulse/main/assets/icon/icon.png"
+    alt="Fact Dynamics logo"
+    width="80"
+    height="80"
+    style={{ borderRadius: '14px' }}
+  />
+</p>
+
+**Hackathon Submission** - Built for Perplexity Hackathon in Information Tools & Deep Research categories.
+
+Fact Dynamics is a cross-platform Flutter app that provides real-time fact-checking for spoken content and images. Perfect for live debates, presentations, and on-the-fly information verification.
+
+
+## Features
+
+* Real-time speech transcription and fact-checking during live conversations
+* Image text extraction and claim verification with source citations
+* Claim rating system (TRUE, FALSE, MISLEADING, UNVERIFIABLE) with explanations
+* Source Citations** - Provides authoritative URLs backing each verdict
+
+* Debate mode with continuous speech recognition and streaming feedback
+* User authentication via Firebase (Google, Email) with persistent chat history
+* Cross-platform support for iOS, Android, and Web
+
+## Prerequisites
+
+* Flutter SDK 3.0.0 or newer
+* Dart SDK 2.17.0 or newer
+* Firebase CLI for authentication and database setup
+* Perplexity API key for Sonar integration
+* Device with microphone access for speech recognition
+
+## Installation (Follow Detailed guideline on the Repository)
+
+```bash
+git clone https://github.com/vishnu32510/fact_pulse.git
+cd fact_pulse
+flutter pub get
+```
+
+## Usage
+
+**Real-time Speech Fact-Checking:**
+- Streams 5-second audio chunks through Flutter's `speech_to_text`
+- Sends transcribed snippets to Sonar API with structured prompts
+- Returns JSON with claims, ratings (TRUE/FALSE/MISLEADING/UNVERIFIABLE), explanations, and sources
+
+**Image Analysis:**
+- Uploads images/URLs to Sonar API for text extraction
+- Verifies extracted claims against authoritative sources
+- Provides comprehensive analysis with source attribution
+
+## Screenshots
+
+<table>
+  <tr>
+    <td>
+      <img
+        src="https://raw.githubusercontent.com/vishnu32510/fact_pulse/main/assets/screenshots/2.%20Dashboard.png"
+        alt="Dashboard"
+        width="200"
+      />
+    </td>
+    <td>
+      <img
+        src="https://raw.githubusercontent.com/vishnu32510/fact_pulse/main/assets/screenshots/4.%20Fact%20Checks(Speech,%20Debate,%20Image).png"
+        alt="Fact checking interface"
+        width="200"
+      />
+    </td>
+  </tr>
+</table>
+
+## Code Explanation
+
+* Frontend: Flutter with BLoC pattern for state management targeting iOS, Android, and Web
+* Backend: Firebase (Firestore, Authentication) for user data and chat history persistence  
+* Speech Processing: speech_to_text package for real-time audio transcription
+* API Integration: Custom Dart client calling Perplexity Sonar API with structured prompts
+* Image Processing: Built-in image picker with base64 encoding for multimodal analysis
+* Data Architecture: Firestore collections per user with subcollections for debates, speeches, and images
+
+## Open Source SDKs
+
+Built two reusable packages for the Flutter community:
+- **[perplexity_dart](https://pub.dev/packages/perplexity_dart)** - Core Dart SDK for Perplexity API
+- **[perplexity_flutter](https://pub.dev/packages/perplexity_flutter)** - Flutter widgets and BLoC integration
+
+
+## Links
+
+- **[GitHub Repository](https://github.com/vishnu32510/fact_pulse)** - Full source code
+- **[Live Demo](https://fact-pulse.web.app/)** - Try the web version
+- **[Demo Video](https://youtu.be/92IoX19Djtc)** - Watch it in action
+- **[Devpost Submission](https://devpost.com/software/fact-dynamics)** - Hackathon entry 

docs/showcase/index.mdx

@@ -0,0 +1,78 @@
+---
+title: PerplexiGrid | Interactive Analytics Dashboards
+description: Instantly generate analytics dashboards from natural language using live data via Perplexity Sonar API.
+sidebar_position: 5
+keywords: [perplexigrid, dashboard, analytics, BI, AI, Perplexity, sonar, echarts, supabase]
+---
+
+**PerplexiGrid** turns natural language into rich, interactive dashboards. Connect your data and mix it with live web data, ask a question, and let the Sonar API do the rest! Complete with drag-and-drop layout, AI widget generation, and ECharts-powered visualizations.
+
+## Features
+
+* **Natural Language to Dashboards**: Convert plain English prompts into fully functional analytics dashboards with 25+ widget types
+* **Live Data Integration**: Blend your own data sources with real-time web data for comprehensive insights
+* **Interactive Grid Layout**: Drag-and-drop interface for customizing dashboard layouts and styling
+* **AI-Powered Refinement**: Refine or add widgets using conversational updates
+* **Export & Share**: Generate PDF exports, high-res images, and shareable dashboard links
+
+## How it uses Sonar
+
+PerplexiGrid leverages the Sonar API through four specialized modes:
+
+* **Full Dashboard Generation (f1)**: Creates comprehensive dashboards with multiple widgets using Sonar-pro's advanced capabilities
+* **Lightweight Mode (l1)**: Generates quick visualizations for embedded systems and real-time applications
+* **Dashboard Updates (r1)**: Enables dynamic modifications through natural language while maintaining context
+* **Widget Refinement (r2)**: Provides precise control over individual widget updates
+
+The system uses structured JSON schema responses to ensure consistent, ECharts-compatible output that can be directly rendered as interactive visualizations.
+
+## Usage
+
+1. Open the app and start a new dashboard  
+2. Prompt it like: _"Show me market trends in AI startups in 2024"_  (Sonar generates chart configs, which are parsed and rendered as live widgets)
+
+![Prompt #1](https://www.perplexigrid.com/guide/prompt_dark.gif)
+
+3. Rearrange and style the widgets with the grid interface  
+
+![Prompt #2](https://www.perplexigrid.com/guide/move_dark.gif)
+![Prompt #3](https://www.perplexigrid.com/guide/customize_dark.gif)
+
+5. Add your own datasources to blend your data with live web data
+
+![Prompt #4](https://www.perplexigrid.com/guide/datasource_dark.gif)
+
+6. Refine them via text prompts or export the dashboard as needed  
+7. Collaborate and share easily
+
+![Prompt #5](https://www.perplexigrid.com/guide/invite_dark.gif)
+
+## Code Explanation
+
+The user sends messages that are turned into prompts to a Supabase Edge Function that wraps the Perplexity Sonar API.  
+Depending on the mode (`f1`, `l1`, `r1`, or `r2`), the function generates full structured outputs for dashboards, lightweight visualizations, or targeted updates.  
+The generated layout is parsed into structured widget definitions and passed through our widget creation engine.
+
+Explore our [main sonar-api service here.](https://github.com/PetarRan/perplexigrid/blob/main/server/supabase/functions/_shared/perplexityService.ts)
+
+## Prompt Modes
+
+| Mode | Description | Use Case | Notes |
+|------|-------------|----------|-------|
+| `f1` | First-time full dashboard generation | User starts with an empty canvas and enters an initial prompt | Produces a complete dashboard layout with multiple widgets |
+| `l1` | Lightweight dashboard generation | Used for quick insights or previews with minimal tokens | Faster and cheaper, but returns fewer widgets with less instruction depth |
+| `r1` | Full dashboard regeneration | User wants to replace all existing widgets with a new prompt | Rebuilds the entire dashboard while keeping layout intact |
+| `r2` | Targeted widget update | User wants to change a specific widget (e.g. "make this a pie chart") | Only the selected widget is modified based on the new instruction |
+
+## Tech Stack
+
+* **Frontend**: React + Vite (TypeScript), ECharts, react-grid-layout
+* **Backend**: Supabase Edge Functions (TypeScript on Deno)
+* **AI Engine**: Perplexity Sonar-Pro
+* **Infrastructure**: Supabase (PostgreSQL, RLS, Auth), Vercel deployment
+
+## Links
+
+- [GitHub Repository](https://github.com/PetarRan/perplexigrid)
+- [Live Demo](https://app.perplexigrid.com)
+- [Website](https://www.perplexigrid.com)