> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ItzCrazyKns/Perplexica/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> High-level flow of how Perplexica answers questions with AI and search

This guide explains what happens when you ask Perplexica a question, from the moment you send a message to when you receive a cited, intelligent answer.

For component-level architecture details, see [Architecture](/advanced/architecture).

## Overview

When you send a message in the UI, the app calls `POST /api/chat`. At a high level, three things happen:

<Steps>
  <Step title="Classify the question">
    Decide what to do next based on the query
  </Step>

  <Step title="Run research and widgets in parallel">
    Gather information and structured data simultaneously
  </Step>

  <Step title="Write the final answer">
    Generate a response with citations
  </Step>
</Steps>

Let's walk through each step in detail.

## Step 1: Classification

Before searching or answering, Perplexica runs a classification step to understand the question and plan the response.

### What the classifier decides

The classifier (`src/lib/agents/search/classifier.ts`) analyzes the query and determines:

* **Should we do research?** Some questions don't need web search (e.g., "What did we discuss earlier?")
* **Which widgets are relevant?** Weather, stocks, or calculations
* **What sources to use?** Web, academic papers, or discussions
* **How to rewrite the query** into a clearer, standalone form that works without conversation context

<Info>
  The classifier uses a structured schema with boolean flags for each decision. This ensures consistent, predictable behavior.
</Info>

### Classification output example

```json theme={null}
{
  "classification": {
    "skipSearch": false,
    "personalSearch": false,
    "academicSearch": true,
    "discussionSearch": false,
    "showWeatherWidget": false,
    "showStockWidget": false,
    "showCalculationWidget": false
  },
  "standaloneFollowUp": "How does quantum entanglement work?"
}
```

## Step 2: Parallel execution

After classification, Perplexica runs two processes in parallel for optimal performance:

### Widgets

Widgets are small, structured helpers that provide real-time data:

<CardGroup cols={3}>
  <Card title="Weather" icon="cloud-sun">
    Current conditions and forecasts based on location
  </Card>

  <Card title="Stocks" icon="chart-line">
    Real-time market data and stock prices
  </Card>

  <Card title="Calculations" icon="calculator">
    Evaluate mathematical expressions
  </Card>
</CardGroup>

**Key characteristics**:

* Run independently of research
* Show structured UI cards while the answer is being generated
* Provide helpful context but are **not cited as sources**
* Executed by `src/lib/agents/search/widgets/executor.ts`

<Note>
  Widgets complete quickly and appear in the UI before the final answer, giving users immediate value.
</Note>

### Research

If research is needed (based on classification), the researcher gathers information in the background:

**Research capabilities** (`src/lib/agents/search/researcher/actions/`):

* **Web search**: General information via SearXNG meta-search
* **Academic search**: Scholarly papers and research articles
* **Social search**: Discussion forums and community insights
* **Upload search**: Semantic search over user-uploaded files (PDFs, documents)
* **URL scraping**: Direct content extraction from specific URLs

**How research works**:

1. The researcher receives the standalone query and enabled sources
2. It selects appropriate tools based on the classification
3. Tools run and gather relevant content
4. Results are deduplicated and ranked
5. A set of "search findings" is returned with metadata (title, URL, content)

Location: `src/lib/agents/search/researcher/index.ts`

## Step 3: Answer generation

Once Perplexica has enough context from research and widgets, it generates the final response.

### Context assembly

The system combines two types of context:

<Accordion title="Search results (citable)">
  ```xml theme={null}
  <search_results note="These are the search results and assistant can cite these">
    <result index=1 title="...">
      Content from web search...
    </result>
    <result index=2 title="...">
      Content from academic paper...
    </result>
  </search_results>
  ```

  These can and should be cited in the answer.
</Accordion>

<Accordion title="Widget results (non-citable)">
  ```xml theme={null}
  <widgets_result noteForAssistant="Its output is already showed to the user, assistant can use this information to answer the query but do not CITE this as a source">
    <result>
      Weather data...
    </result>
  </widgets_result>
  ```

  These provide context but should not be cited.
</Accordion>

### Optimization modes

You can control the tradeoff between speed and quality using `optimizationMode`:

* **Speed**: Fast responses with lighter processing
* **Balanced**: Default mode balancing speed and thoroughness
* **Quality**: Deep analysis with more comprehensive answers

The mode affects:

* How much context is gathered
* The complexity of the writer prompt
* Model parameters (temperature, top-p, etc.)

### Streaming response

The answer is streamed to the user in real-time:

1. Writer prompt is constructed with search context and system instructions
2. LLM begins generating the response
3. Each chunk is emitted to the user via Server-Sent Events (SSE)
4. The UI updates progressively as text arrives
5. When complete, the full response is saved to the database

Location: `src/lib/agents/search/index.ts:122-166`

## How citations work

Perplexica prompts the model to cite the references it uses. The citation system works as follows:

1. **Source numbering**: Each search result has an index
2. **Inline citations**: The model references sources by index (e.g., \[1], \[2])
3. **UI rendering**: Citations are rendered as clickable links alongside the answer
4. **Supporting links**: Each citation links to the original source

<Info>
  The writer prompt explicitly instructs the model to cite sources. This is handled by the prompt template in `src/lib/prompts/search/writer.ts`.
</Info>

## Media search (images and videos)

Image and video search use separate, specialized endpoints:

### How it differs

* **Endpoint**: `POST /api/images` and `POST /api/videos`
* **Process**:
  1. Generate a focused query using the chat model
  2. Fetch matching results from the search backend
  3. Return structured media results
* **No research phase**: These are pure search operations
* **No citations**: Results are displayed as a gallery

Location: `src/lib/agents/media/image.ts` and `src/lib/agents/media/video.ts`

## Search API for integrations

If you're integrating Perplexica into another product, use `POST /api/search`.

### Response format

```json theme={null}
{
  "message": "The generated answer with citations...",
  "sources": [
    {
      "title": "Source Title",
      "url": "https://example.com",
      "snippet": "Relevant excerpt..."
    }
  ]
}
```

### Streaming mode

Enable streaming by setting `stream: true` in your request:

```typescript theme={null}
fetch('/api/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'How does quantum computing work?',
    stream: true
  })
});
```

The response will be streamed as Server-Sent Events.

## Complete flow diagram

Here's the complete flow from question to answer:

```mermaid theme={null}
graph TD
    A[User sends message] --> B[POST /api/chat]
    B --> C[Classification]
    C --> D{Research needed?}
    D -->|Yes| E[Researcher]
    D -->|No| F[Skip research]
    C --> G[Widget executor]
    E --> H[Web search]
    E --> I[Academic search]
    E --> J[Upload search]
    G --> K[Weather widget]
    G --> L[Stock widget]
    G --> M[Calculation widget]
    H --> N[Assemble context]
    I --> N
    J --> N
    F --> N
    K --> N
    L --> N
    M --> N
    N --> O[Generate answer with citations]
    O --> P[Stream response to user]
    P --> Q[Save to database]
```

## Performance optimizations

Perplexica is designed for speed:

* **Parallel execution**: Widgets and research run simultaneously
* **Streaming**: Users see responses as they're generated
* **Efficient prompts**: Prompts are optimized per mode
* **Caching**: Provider connections are reused
* **Database indexes**: Fast chat and message lookups

## Next steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="building" href="/advanced/architecture">
    Deep dive into components and code structure
  </Card>

  <Card title="API Reference" icon="code" href="/api/overview">
    Integrate Perplexica into your applications
  </Card>
</CardGroup>