# What Data Sources Does PI Desktop Support? A Complete Technical Guide

> Explore supported data sources for PI Desktop. Learn about model and plugin registry sources like bundled, discovered, builtin, and installed in this technical guide.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: how-to-guide
- Published: 2026-09-12

---

**PI Desktop supports four primary model sources (`bundled`, `discovered`, `user`, `recent`) and four plugin registry sources (`builtin`, `dev`, `installed`, `marketplace`), each rigorously defined in the runtime specification files.**

The vastsa/PI-Desktop repository implements a strict taxonomy for data origins that controls how models, plugins, and session data are accessed. Understanding what data sources PI Desktop supports is essential for developers integrating with the host API, building plugins, or configuring provider connections.

## Model Catalog Data Sources

According to [`docs/spec/03-runtime/13-model-catalog-and-selection.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/03-runtime/13-model-catalog-and-selection.md), the runtime distinguishes four distinct **model sources** that determine how AI models enter the system. These sources filter what appears in the model picker and govern update semantics.

### Bundled Models

The `bundled` source refers to static snapshots shipped with the application. These models reside in [`resources/models.dev/api.json`](https://github.com/vastsa/PI-Desktop/blob/main/resources/models.dev/api.json) and provide a baseline set of providers that work offline. Because they are compiled into the binary, bundled models never require remote validation and serve as the fallback when network discovery fails.

### Discovered Models

The `discovered` source represents rows fetched from remote provider catalogs such as OpenAI, Anthropic, or other compatible endpoints. When the host performs a discovery sweep, it queries these remote APIs and hydrates the local catalog with available model IDs, pricing tiers, and capability flags. This source is dynamic and updates each time the user refreshes the catalog.

### User Models

The `user` source captures models manually added via the Settings UI. When a user enters a custom endpoint or API key for a provider not present in the bundled or discovered sets, the host writes a row with `source = 'user'` into the models table. These entries persist across restarts and are scoped to the user profile.

### Recent Models

The `recent` source draws from the MRU (Most Recently Used) table. Rather than being a permanent catalog entry, this source provides quick access to the last selected models across sessions. The host maintains this list automatically based on selection history.

### Cache and Refresh Helpers

Internal lookup helpers exposed to the API surface include two additional source modifiers:

- **`cache`** – Hydrates rows from local storage that were previously discovered, avoiding redundant network calls.
- **`refresh`** – Forces a fresh remote discovery; if the network call fails, the host transparently falls back to the bundled snapshot.

## Plugin Registry Sources

As documented in [`docs/spec/07-plugins/11-plugin-storage-isolation.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/07-plugins/11-plugin-storage-isolation.md), PI Desktop isolates plugin data based on four **plugin sources** that determine visibility, permissions, and storage locations.

### Builtin Plugins

The `builtin` source identifies plugins shipped with the host binary, such as the Files view or default system integrations. These plugins receive elevated trust levels and access to protected APIs because they are code-signed and distributed with the core application.

### Dev Plugins

The `dev` source refers to plugins loaded from a development folder on the local filesystem. These are typically unpacked directories containing uncompiled source code. The host grants `dev` plugins expanded logging and hot-reload capabilities but may restrict certain marketplace-specific APIs.

### Installed Plugins

The `installed` source indicates plugins the user has installed from a `.piplug` package file. Once installed, these plugins reside in the application data directory and receive a private storage sandbox via `pi.plugin.getDataPath()`.

### Marketplace Plugins

The `marketplace` source denotes plugins published in the external plugin-center catalog. When a user installs from the marketplace, the host validates the package signature and assigns the `marketplace` origin, which determines update-checking behavior and trust boundaries.

## Session Import Origins

When a plugin imports historic session data, it must declare the **origin** that produced the rows. The schema accepts `installed`, `dev`, or `marketplace` (mirroring the plugin registry taxonomy) to guarantee that import operations stay scoped to the owning plugin. This prevents cross-plugin data leakage and maintains audit trails. The `pi.session.import()` method enforces this scoping by validating the `source` parameter against the calling plugin's registered origin.

## Provider Configuration Sources

The provider-config schema, defined in [`docs/spec/03-runtime/12-provider-config-schema.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/03-runtime/12-provider-config-schema.md), aligns with the model-source taxonomy. A provider configuration can be:

- **`bundled`** – Built-in defaults for known services.
- **`discovered`** – Automatically generated configs from remote catalog metadata.
- **`user`** – Manually entered endpoints and API keys via the Settings UI.

This alignment ensures that provider capabilities match the provenance of their underlying models.

## Accessing Data Sources Programmatically

The host API surfaces these sources through strongly-typed methods in [`packages/agent-runtime/src/api.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/agent-runtime/src/api.ts) (or equivalent runtime implementation). Developers can filter queries and import operations by specifying the `source` parameter.

List only bundled models to ensure offline availability:

```javascript
const bundled = await pi.models.list({ source: 'bundled' });
console.log('Bundled models:', bundled);

```

Fetch discovered models from remote catalogs:

```javascript
const discovered = await pi.models.list({ source: 'discovered' });
console.log('Discovered models:', discovered);

```

Import session rows that originated from an installed plugin:

```javascript
await pi.session.import({
  source: 'installed',
  pluginId: 'com.example.my-plugin',
  rows: [{ /* session data */ }]
});

```

Retrieve the private data directory for a plugin, where the source determines visibility:

```javascript
const dataPath = pi.plugin.getDataPath();
// Returns path based on whether plugin is dev, installed, or marketplace

```

## Summary

- **Four model sources** (`bundled`, `discovered`, `user`, `recent`) control how AI models appear in the catalog, documented in [`docs/spec/03-runtime/13-model-catalog-and-selection.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/03-runtime/13-model-catalog-and-selection.md).
- **Two internal helpers** (`cache`, `refresh`) optimize model lookup without exposing new data origins.
- **Four plugin sources** (`builtin`, `dev`, `installed`, `marketplace`) govern storage isolation and trust boundaries per [`docs/spec/07-plugins/11-plugin-storage-isolation.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/07-plugins/11-plugin-storage-isolation.md).
- **Session imports** must declare an origin matching the plugin's registry source to maintain scoping guarantees.
- **Provider configs** mirror the model-source taxonomy (`bundled`, `discovered`, `user`) for consistency.
- **Host API methods** including `pi.models.list()`, `pi.session.import()`, and `pi.plugin.getDataPath()` enforce these source constraints at runtime.

## Frequently Asked Questions

### What is the difference between bundled and discovered models in PI Desktop?

**Bundled models** are static snapshots compiled into the application at [`resources/models.dev/api.json`](https://github.com/vastsa/PI-Desktop/blob/main/resources/models.dev/api.json) and available offline. **Discovered models** are fetched dynamically from remote provider catalogs like OpenAI or Anthropic when the user refreshes the catalog or the host performs a background sync.

### How do I filter models by source in PI Desktop?

Use the `pi.models.list()` method with the `source` parameter set to `bundled`, `discovered`, `user`, or `recent`. For example, `await pi.models.list({ source: 'user' })` returns only user-defined models added via the Settings UI.

### Can plugins access data from other plugin sources?

No. The plugin storage isolation model prevents cross-origin access. A plugin with source `dev` cannot read the data directory of an `installed` or `marketplace` plugin. The `pi.plugin.getDataPath()` method returns a sandboxed path specific to the calling plugin's registered source.

### What happens when a remote model discovery fails?

When the `refresh` source is requested and the remote catalog is unreachable, the host falls back to the `bundled` snapshot automatically. This guarantees that the model picker remains populated even when network connectivity is lost.