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

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, 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 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, 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, 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 (or equivalent runtime implementation). Developers can filter queries and import operations by specifying the source parameter.

List only bundled models to ensure offline availability:

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

Fetch discovered models from remote catalogs:

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

Import session rows that originated from an installed plugin:

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:

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.
• 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.
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}