feat(perplexity): add Agent API presets and deprecate legacy Sonar models

.changeset/strong-agents-replace-sonar.md

@@ -0,0 +1,11 @@
+---
+'baseai': minor
+'@baseai/core': minor
+---
+
+Add Perplexity Agent API support with the `fast`, `low`, `medium`, and `high`
+presets for local BaseAI Pipes. The existing Perplexity Sonar identifiers remain
+on Chat Completions but are deprecated ahead of their scheduled September 27,
+2026 shutdown; existing Pipes are not migrated automatically. Agent responses
+preserve the executing model and available usage, provider HTTP errors retain
+their BaseAI status categories, and tool-free Core streams return immediately.

apps/baseai.dev/content/docs/docs/supported-models-and-providers.mdx

@@ -7,7 +7,7 @@ tags:
     - llm providers
     - models
 published: 2024-09-24
-modified: 2024-09-24
+modified: 2026-08-28
 ---
 
 # Supported LLM models and providers
@@ -150,7 +150,99 @@ Learn more about [using Ollama models](/docs/guides/using-ollama-models) in Base
 
 ### Perplexity
 
-| Model                                                                                                    | Provider   | Owner | Context | Cost*                                      |
+Use a Perplexity Agent API preset for new local BaseAI integrations. Presets select and evolve their underlying model and built-in search tools dynamically.
+
+| Agent preset | BaseAI ID                                  | Best for                                         | Cost    |
+|--------------|--------------------------------------------|--------------------------------------------------|---------|
+| Fast         | <InlineCopy content="perplexity:fast" />   | Quick lookups and short summaries with citations | Dynamic |
+| Low          | <InlineCopy content="perplexity:low" />    | Everyday, light multi-step research              | Dynamic |
+| Medium       | <InlineCopy content="perplexity:medium" /> | Multi-hop research across many sources           | Dynamic |
+| High         | <InlineCopy content="perplexity:high" />   | Deep research and broad source coverage          | Dynamic |
+
+This first Agent integration supports system, user, and assistant text; non-streaming responses; streaming answer text; and preset search. Custom tools, tool-result replay, background runs, file outputs, and explicit Agent model selection are not supported. Citation metadata is included on non-streaming responses; streamed citation metadata is not exposed because the existing BaseAI stream chunk contract has no compatible citation field.
+
+<Note>
+These Agent identifiers are supported only by the public BaseAI OSS local runtime. This integration does not change, validate, or propose fixes for Langbase-hosted or other proprietary systems.
+</Note>
+
+<Warning>
+Sonar Chat Completions is now [**Agent API**](https://docs.perplexity.ai/docs/agent-api/quickstart). Migrate by September 27, 2026. View the [**Migration Guide**](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/overview).
+
+The following legacy Perplexity Sonar identifiers remain routed through Chat Completions. Existing Pipes are not migrated automatically.
+
+<ul>
+	<li><code>perplexity:llama-3.1-sonar-huge-128k-online</code></li>
+	<li><code>perplexity:llama-3.1-sonar-large-128k-online</code></li>
+	<li><code>perplexity:llama-3.1-sonar-small-128k-online</code></li>
+	<li><code>perplexity:llama-3.1-sonar-large-128k-chat</code></li>
+	<li><code>perplexity:llama-3.1-sonar-small-128k-chat</code></li>
+</ul>
+</Warning>
+
+#### Migrate a BaseAI Pipe
+
+Choose an Agent alias by workload from the table above; the historical BaseAI identifiers do not have an exact one-to-one mapping to today's Sonar product names. Existing Pipes are not changed automatically.
+
+For example, keep the rest of the Pipe configuration and replace its legacy model ID with the preset that fits the workload.
+
+Before:
+
+```ts
+const researchPipe = (): PipeI => ({
+	model: 'perplexity:llama-3.1-sonar-small-128k-online',
+	max_tokens: 1000,
+	temperature: 0.7,
+	top_p: 1,
+	// ...the remaining Pipe fields
+});
+```
+
+After:
+
+```ts
+const researchPipe = (): PipeI => ({
+	model: 'perplexity:fast',
+	max_tokens: 1000,
+	temperature: 0.7,
+	top_p: 1,
+	// ...the remaining Pipe fields
+});
+```
+
+BaseAI requires `max_tokens`, `temperature`, and `top_p`. Agent API receives them as request values (`max_tokens` becomes `max_output_tokens`), so they override the selected preset's tuned defaults. Review these values while migrating.
+
+Set both keys in the local caller's `.env` file:
+
+```bash
+LANGBASE_API_KEY="your-langbase-key"
+PERPLEXITY_API_KEY="your-perplexity-key"
+```
+
+`@baseai/core` reads `PERPLEXITY_API_KEY` from the local process and sends it as `llmApiKey` to the BaseAI server on `localhost:9000`; the local server uses it only for the Perplexity provider request. `LANGBASE_API_KEY` is read by the Pipe configuration. Keep both values server-side and out of source control.
+
+From the repository root, build and run the workspace-linked Node example:
+
+```bash
+pnpm install
+pnpm --filter example-nodejs check
+pnpm --filter example-nodejs baseai dev
+```
+
+Then run either request in a second terminal:
+
+```bash
+# Non-streaming answer plus citation metadata
+pnpm --filter example-nodejs pipe.perplexity.agent
+
+# Streaming answer text through Pipe.run({ stream: true })
+pnpm --filter example-nodejs pipe.perplexity.agent.stream
+```
+
+This PR changes only the public BaseAI local runtime; Langbase-hosted execution and rollout are outside its scope. Custom tools and tool-result replay, streamed citation metadata, background mode, file output, explicit Agent models, `xhigh`, and `wide-research` are not supported in this integration.
+
+Read the [migration overview](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/overview) for workload guidance and the [field-by-field migration guide](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/how-to) for request, response, citation, and streaming changes.
+
+| Legacy model                                                                                             | Provider   | Owner | Context | Cost*                                      |
 |----------------------------------------------------------------------------------------------------------|------------|-------|---------|--------------------------------------------|
 | llama-3.1-sonar-huge-128k-online   <br/> ID:  <InlineCopy content="perplexity:llama-3.1-sonar-huge-128k-online" />  | Perplexity | Meta  | 127,072 | $5            prompt <br/> $5  completion  |
 | llama-3.1-sonar-large-128k-online  <br/> ID:  <InlineCopy content="perplexity:llama-3.1-sonar-large-128k-online" /> | Perplexity | Meta  | 127,072 | $1            prompt <br/> $1 completion   |

examples/nodejs/baseai/pipes/perplexity-agent.ts

@@ -0,0 +1,32 @@
+import {PipeI} from '@baseai/core';
+
+const perplexityAgentPipe = (): PipeI => ({
+	apiKey: process.env.LANGBASE_API_KEY!,
+	name: 'perplexity-agent',
+	description: 'Research with a Perplexity Agent API preset.',
+	status: 'private',
+	model: 'perplexity:fast',
+	stream: true,
+	json: false,
+	store: true,
+	moderate: true,
+	top_p: 1,
+	max_tokens: 1000,
+	temperature: 0.7,
+	presence_penalty: 1,
+	frequency_penalty: 1,
+	stop: [],
+	tool_choice: 'auto',
+	parallel_tool_calls: true,
+	messages: [
+		{
+			role: 'system',
+			content: 'Answer concisely and cite sources for factual claims.',
+		},
+	],
+	variables: [],
+	memory: [],
+	tools: [],
+});
+
+export default perplexityAgentPipe;

examples/nodejs/examples/pipe.perplexity-agent.stream.ts

@@ -0,0 +1,25 @@
+import 'dotenv/config';
+import {getRunner, Pipe} from '@baseai/core';
+import perplexityAgentPipe from '../baseai/pipes/perplexity-agent';
+
+const pipe = new Pipe(perplexityAgentPipe());
+
+async function main() {
+	const {stream} = await pipe.run({
+		messages: [
+			{
+				role: 'user',
+				content:
+					'What changed in the latest JavaScript language release?',
+			},
+		],
+		stream: true,
+	});
+
+	const runner = getRunner(stream);
+	runner.on('content', content => process.stdout.write(content));
+	runner.on('end', () => process.stdout.write('\n'));
+	runner.on('error', error => console.error(error));
+}
+
+main();

examples/nodejs/examples/pipe.perplexity-agent.ts

@@ -0,0 +1,22 @@
+import 'dotenv/config';
+import {Pipe} from '@baseai/core';
+import perplexityAgentPipe from '../baseai/pipes/perplexity-agent';
+
+const pipe = new Pipe(perplexityAgentPipe());
+
+async function main() {
+	const response = await pipe.run({
+		messages: [
+			{
+				role: 'user',
+				content:
+					'What changed in the latest JavaScript language release?',
+			},
+		],
+	});
+
+	console.log(response.completion);
+	console.log(response.choices[0]?.message.citationMetadata);
+}
+
+main();

examples/nodejs/package.json

@@ -7,21 +7,27 @@
 	"main": "index.js",
 	"scripts": {
 		"baseai": "baseai",
+		"check": "pnpm --filter baseai build && pnpm type-check && baseai --help",
 		"pipe.run": "npx tsx ./examples/pipe.run.ts",
 		"pipe.run.stream": "npx tsx ./examples/pipe.run.stream.ts",
 		"pipe.run.stream.loop": "npx tsx ./examples/pipe.run.stream.loop.ts",
+		"pipe.perplexity.agent": "npx tsx ./examples/pipe.perplexity-agent.ts",
+		"pipe.perplexity.agent.stream": "npx tsx ./examples/pipe.perplexity-agent.stream.ts",
 		"pipe.generate.text": "npx tsx ./examples/pipe.generate.text.ts",
-		"pipe.stream.text": "npx tsx ./examples/pipe.stream.text.ts"
+		"pipe.stream.text": "npx tsx ./examples/pipe.stream.text.ts",
+		"type-check": "pnpm --filter @baseai/core build && tsc --noEmit"
 	},
 	"keywords": [],
 	"author": "Ahmad Awais <me@AhmadAwais.com> (https://twitter.com/MrAhmadAwais)",
 	"license": "UNLICENSED",
 	"dependencies": {
-		"@baseai/core": "^0.9.43",
+		"@baseai/core": "workspace:*",
 		"dotenv": "^16.4.5"
 	},
 	"devDependencies": {
-		"baseai": "^0.9.44",
-		"tsx": "^4.19.0"
+		"@types/node": "^22.6.1",
+		"baseai": "workspace:*",
+		"tsx": "^4.19.0",
+		"typescript": "^5.6.2"
 	}
 }

examples/nodejs/readme.md

@@ -4,6 +4,58 @@ BaseAI Node.js examples.
 
 Please read the [documentation](https://baseai.dev/docs) for more information.
 
+## Perplexity Agent API migration example
+
+Sonar Chat Completions is now [**Agent API**](https://docs.perplexity.ai/docs/agent-api/quickstart). Migrate by September 27, 2026. View the [**Migration Guide**](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/overview).
+
+The four opt-in local BaseAI Agent aliases are `perplexity:fast` for quick lookups, `perplexity:low` for everyday research, `perplexity:medium` for multi-hop research, and `perplexity:high` for deep research. Choose by workload; do not assume an exact mapping from these historical BaseAI IDs:
+
+-   `perplexity:llama-3.1-sonar-huge-128k-online`
+-   `perplexity:llama-3.1-sonar-large-128k-online`
+-   `perplexity:llama-3.1-sonar-small-128k-online`
+-   `perplexity:llama-3.1-sonar-large-128k-chat`
+-   `perplexity:llama-3.1-sonar-small-128k-chat`
+
+Existing Pipes are not migrated automatically. Change only the model ID and review the required sampling fields:
+
+```diff
+-model: 'perplexity:llama-3.1-sonar-small-128k-online',
++model: 'perplexity:fast',
+ max_tokens: 1000,
+ temperature: 0.7,
+ top_p: 1,
+```
+
+BaseAI sends `max_tokens` as Agent `max_output_tokens` and sends `temperature` and `top_p`; supplied values override preset defaults.
+
+Create `examples/nodejs/.env` with both server-side keys:
+
+```bash
+LANGBASE_API_KEY="your-langbase-key"
+PERPLEXITY_API_KEY="your-perplexity-key"
+```
+
+The local Core caller reads `PERPLEXITY_API_KEY` and passes it to the BaseAI server on `localhost:9000` for the provider request. `LANGBASE_API_KEY` is read by the Pipe configuration. Do not commit either value.
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter example-nodejs check
+pnpm --filter example-nodejs baseai dev
+```
+
+In another terminal, run the non-streaming example to print completion text and typed `citationMetadata`, or the separate streaming example to consume the public Core stream:
+
+```bash
+pnpm --filter example-nodejs pipe.perplexity.agent
+pnpm --filter example-nodejs pipe.perplexity.agent.stream
+```
+
+This is public BaseAI OSS local-runtime support only. It does not change, validate, or propose fixes for Langbase-hosted or other proprietary systems. Custom tools and tool replay, streamed citation metadata, background mode, file output, explicit Agent models, `xhigh`, and `wide-research` are unsupported. See the [migration overview](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/overview) and [field-by-field guide](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/how-to).
+
+## Other examples
+
 ```sh
 # Install the dependencies
 npm install
@@ -22,6 +74,8 @@ npx baseai pipe
 npm run pipe.run
 npm run pipe.run.stream
 npm run pipe.run.stream.loop
+npm run pipe.perplexity.agent
+npm run pipe.perplexity.agent.stream
 npm run pipe.generate.text
 npm run pipe.stream.text
 ```

examples/nodejs/tsconfig.json

@@ -0,0 +1,14 @@
+{
+	"compilerOptions": {
+		"esModuleInterop": true,
+		"lib": ["ES2022", "DOM", "DOM.Iterable"],
+		"module": "ESNext",
+		"moduleResolution": "Bundler",
+		"noEmit": true,
+		"skipLibCheck": true,
+		"strict": true,
+		"target": "ES2022",
+		"types": ["node"]
+	},
+	"include": ["baseai/**/*.ts", "examples/**/*.ts"]
+}

packages/baseai/CHANGELOG.md

@@ -1,5 +1,17 @@
 # baseai
 
+## Unreleased
+
+### Minor Changes
+
+-   Add local Perplexity Agent API support with the `fast`, `low`, `medium`, and
+    `high` presets, including provider-local text streaming, citation mapping,
+    executing-model reporting, optional usage, and status-preserving errors.
+-   Deprecate the five legacy `perplexity:llama-3.1-sonar-*` identifiers ahead
+    of their scheduled September 27, 2026 shutdown. Existing Pipes are not
+    migrated automatically; follow the [Perplexity Sonar migration
+    guide](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/overview).
+
 ## 0.9.44
 
 ### Patch Changes

packages/baseai/src/data/models.ts

@@ -96,9 +96,9 @@ export const OLLAMA: string = 'ollama';
 interface Model {
 	id: string;
 	provider: string;
-	promptCost: number;
-	completionCost: number;
-	requestCost?: number;
+	promptCost: number | null;
+	completionCost: number | null;
+	requestCost?: number | null;
 	toolSupport?: {
 		toolChoice: boolean;
 		parallelToolCalls: boolean;
@@ -577,6 +577,34 @@ export const modelsByProvider: ModelsByProviderInclCosts = {
 		}
 	],
 	[PERPLEXITY]: [
+		{
+			id: 'fast',
+			provider: PERPLEXITY,
+			promptCost: null,
+			completionCost: null,
+			requestCost: null
+		},
+		{
+			id: 'low',
+			provider: PERPLEXITY,
+			promptCost: null,
+			completionCost: null,
+			requestCost: null
+		},
+		{
+			id: 'medium',
+			provider: PERPLEXITY,
+			promptCost: null,
+			completionCost: null,
+			requestCost: null
+		},
+		{
+			id: 'high',
+			provider: PERPLEXITY,
+			promptCost: null,
+			completionCost: null,
+			requestCost: null
+		},
 		{
 			id: 'llama-3.1-sonar-huge-128k-online',
 			provider: PERPLEXITY,