> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipeline

> The Docex worker pipeline is task-agnostic. It classifies the input, plans a strategy, executes it through AI providers, and returns a structured envelope.

# Pipeline

> The Docex worker pipeline is model- and task-agnostic. It does not assume "documents." The only document-specific layer is the optional built-in schema registry, which provides convenience defaults for common extraction tasks.

## Stages

<Steps>
  <Step title="Upload">
    The client requests a presigned upload URL via `POST /v1/uploads/presign`, then uploads the file directly to storage. This keeps large files out of your API request body.
  </Step>

  <Step title="Queue">
    The client submits a run request via `POST /v1/runs` with the upload ID, prompt, and optional schema or workflow hints. The run is queued for processing.
  </Step>

  <Step title="Classify">
    The worker inspects file metadata (type, dimensions, page count) and classifies the task type. This informs provider selection and cost estimation.
  </Step>

  <Step title="Plan">
    The planner resolves candidate providers per step based on the catalog (`catalog.js`). It considers capabilities, costs, and auth requirements to build an execution strategy.
  </Step>

  <Step title="Execute">
    The executor runs the strategy. If a provider fails (timeout, rate limit, error), it automatically falls back to the next candidate in the plan.
  </Step>

  <Step title="Respond">
    The worker wraps the result in a standard run envelope with `status`, `result`, `usage`, `confidence`, and `chargedUsd`. The client polls `GET /v1/runs/:jobId` until completion.
  </Step>
</Steps>

## Execution strategies

The worker supports multiple strategies depending on the task and file:

| Strategy                   | When used                                                  |
| -------------------------- | ---------------------------------------------------------- |
| **Direct multimodal**      | Single image, vision-capable model can handle it directly  |
| **OCR then analyze**       | PDF or image where text extraction improves accuracy       |
| **Generic vision summary** | Open-ended analysis where no structured schema is provided |

## Cost confirmation

Runs exceeding `DOCEX_COST_CONFIRMATION_THRESHOLD_USD` (default `$1.00`) require explicit confirmation via `confirmCost: true` or a `maxCostUsd` budget. The estimate is based on file metadata; refunds are issued if actual cost is below the estimate.