Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

fix: improve tools output

Carl-Gerhard Lindesvärd0e677babbd37
diff --git a/apps/api/src/agents/tools/base.ts b/apps/api/src/agents/tools/base.ts
index 7325e8c61..60fd68f77 100644
--- a/apps/api/src/agents/tools/base.ts
+++ b/apps/api/src/agents/tools/base.ts
@@ -25,6 +25,7 @@ import {
import { runReport, runReportFromConfig } from '@openpanel/mcp';
import {
chatTool,
+ compactEventProperties,
dashboardUrl,
pageContextFilters,
resolveDateRange,
@@ -52,7 +53,7 @@ export const listEventProperties = chatTool(
{
name: 'list_event_properties',
description:
- 'List the property keys available for an event (or all events). Call this before using a property as a filter or breakdown in generate_report.',
+ 'List property keys available for an event (or across all events). Call this before using a property as a filter or breakdown in generate_report. NOTE: dotted sub-keys are rolled up to their root — e.g. all `__query.foo`, `__query.bar`, … are represented by a single `__query` entry. Keys are ordered by how many sub-keys roll up under them (most prominent first). To filter on a specific sub-key like `__query.utm_source`, use that exact full key in `set_property_filters` / breakdowns — the rollup is purely a discovery optimization.',
schema: z.object({
eventName: z
.string()
@@ -60,8 +61,13 @@ export const listEventProperties = chatTool(
.describe('Optional — filter to one event. Omit to list properties across all events.'),
}),
},
- async ({ eventName }, context) =>
- listEventPropertiesCore({ projectId: context.projectId, eventName }),
+ async ({ eventName }, context) => {
+ const raw = await listEventPropertiesCore({
+ projectId: context.projectId,
+ eventName,
+ });
+ return compactEventProperties(raw, { eventName });
+ },
);
export const getEventPropertyValues = chatTool(
diff --git a/apps/api/src/agents/tools/events.ts b/apps/api/src/agents/tools/events.ts
index 797be9ce4..25acc8055 100644
--- a/apps/api/src/agents/tools/events.ts
+++ b/apps/api/src/agents/tools/events.ts
@@ -4,7 +4,12 @@ import {
listEventPropertiesCore,
queryEventsCore,
} from '@openpanel/db';
-import { chatTool, resolveDateRange, truncateRows } from './helpers';
+import {
+ chatTool,
+ compactEventProperties,
+ resolveDateRange,
+ truncateRows,
+} from './helpers';
export const analyzeEventDistribution = chatTool(
{
@@ -136,11 +141,16 @@ export const listPropertiesForEvent = chatTool(
{
name: 'list_properties_for_event',
description:
- 'List property keys available for a specific event (or all events). Useful before correlating or filtering.',
+ 'List property keys available for a specific event (or all events). Useful before correlating or filtering. Dotted sub-keys are rolled up to their root (e.g. all `__query.*` become a single `__query`); ordered by how many sub-keys roll up under each root.',
schema: z.object({
eventName: z.string().optional(),
}),
},
- async ({ eventName }, context) =>
- listEventPropertiesCore({ projectId: context.projectId, eventName }),
+ async ({ eventName }, context) => {
+ const raw = await listEventPropertiesCore({
+ projectId: context.projectId,
+ eventName,
+ });
+ return compactEventProperties(raw, { eventName });
+ },
);
diff --git a/apps/api/src/agents/tools/helpers.ts b/apps/api/src/agents/tools/helpers.ts
index 4286211e2..eb0f065ac 100644
--- a/apps/api/src/agents/tools/helpers.ts
+++ b/apps/api/src/agents/tools/helpers.ts
@@ -95,6 +95,55 @@ export function truncateRows<T>(
return { rows: rows.slice(0, max), total: rows.length, _truncated: true };
}
+/**
+ * Compact output from `listEventPropertiesCore` for consumption by the LLM.
+ *
+ * The raw shape is `{ properties: [{ property_key, event_name }, …] }` ordered
+ * alphabetically and capped at 500 rows. That shape has three token-hungry
+ * problems when passed back as a tool result:
+ *
+ * 1. Dotted sub-keys explode. A single property like `__query` or `data`
+ * with dynamic sub-paths surfaces as hundreds of rows
+ * (`__query.foo`, `__query.bar`, `__query.<uuid>`, …). They flood
+ * alphabetically-first — 300 of them before `country` appears.
+ * 2. `event_name` is repeated on every row. When the caller passed an
+ * `eventName` filter it's a constant string; we only need it once.
+ * 3. The full 500-row dump is rarely necessary — the model uses this
+ * list for filter/breakdown discovery, which is satisfied by the
+ * top ~50 distinct roots.
+ *
+ * This helper collapses dotted keys to their root segment, dedupes, orders
+ * by frequency (how many original sub-keys fell under each root — a decent
+ * "how prominent is this property" signal), and caps the list.
+ */
+export function compactEventProperties(
+ raw: { properties: Array<{ property_key: string; event_name: string }> },
+ options: { eventName?: string; max?: number } = {},
+): {
+ event_name?: string;
+ properties: string[];
+ total: number;
+ _truncated: boolean;
+} {
+ const { eventName, max = 50 } = options;
+ const counts = new Map<string, number>();
+ for (const row of raw.properties) {
+ const dot = row.property_key.indexOf('.');
+ const root = dot >= 0 ? row.property_key.slice(0, dot) : row.property_key;
+ counts.set(root, (counts.get(root) ?? 0) + 1);
+ }
+ const sorted = Array.from(counts.entries())
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+ .map(([key]) => key);
+ const truncated = sorted.length > max;
+ return {
+ ...(eventName ? { event_name: eventName } : {}),
+ properties: truncated ? sorted.slice(0, max) : sorted,
+ total: sorted.length,
+ _truncated: truncated,
+ };
+}
+
/**
* Known range presets that map to date windows via `getDatesFromRange`.
* Anything outside this set (including `"custom"`) is treated as "no
diff --git a/apps/start/src/components/chat/chat-context.tsx b/apps/start/src/components/chat/chat-context.tsx
index b3345a144..0746ebf0e 100644
--- a/apps/start/src/components/chat/chat-context.tsx
+++ b/apps/start/src/components/chat/chat-context.tsx
@@ -3,7 +3,6 @@ import {
isValidModelId,
MODEL_STORAGE_KEY,
} from '@/agents/models';
-import { useAppContext } from '@/hooks/use-app-context';
import { useTRPC } from '@/integrations/trpc/react';
import { useQuery } from '@tanstack/react-query';
import {
@@ -69,6 +68,13 @@ type ChatStateValue = {
agentName: string;
models: readonly ChatModelOption[];
setAgent: (agentName: string) => void;
+ /**
+ * Tri-state derived from the `chat.models` query:
+ * - `null` — query hasn't resolved yet (show the neutral loading state)
+ * - `true` — at least one provider is configured on the API
+ * - `false` — no providers configured → show setup instructions
+ */
+ isAiEnabled: boolean | null;
/**
* Title being streamed for the active conversation, if any. Flips
@@ -97,19 +103,21 @@ function readStoredAgent(): string | null {
}
export function ChatStateProvider({ children }: { children: ReactNode }) {
- const { isAiEnabled } = useAppContext();
const trpc = useTRPC();
- // Fetch the list of models the API can actually serve. When the user has
- // no AI env vars set, `isAiEnabled` is false and we skip the query — the
- // drawer's empty state shows setup instructions instead.
+ // Single source of truth for "is AI configured on the API" — the
+ // `chat.models` query already filters by which provider keys are set, so
+ // an empty `models` array means no OpenAI/Anthropic key and we render the
+ // setup-instructions empty state. No need to leak env vars to the client.
const modelsQuery = useQuery({
...trpc.chat.models.queryOptions(),
- enabled: isAiEnabled,
staleTime: Number.POSITIVE_INFINITY,
});
const models = modelsQuery.data?.models ?? [];
const defaultModelId = modelsQuery.data?.defaultModelId ?? null;
+ const isAiEnabled: boolean | null = modelsQuery.isPending
+ ? null
+ : models.length > 0;
// URL is the source of truth for the active conversation + drawer
// open state. `chatParam`:
// - null → drawer closed
@@ -216,6 +224,7 @@ export function ChatStateProvider({ children }: { children: ReactNode }) {
agentName,
models,
setAgent,
+ isAiEnabled,
streamingTitle,
setStreamingTitle,
pendingMessage,
@@ -233,6 +242,7 @@ export function ChatStateProvider({ children }: { children: ReactNode }) {
agentName,
models,
setAgent,
+ isAiEnabled,
streamingTitle,
pendingMessage,
],
diff --git a/apps/start/src/components/chat/chat-drawer.tsx b/apps/start/src/components/chat/chat-drawer.tsx
index fc3f7c7bc..7c6256539 100644
--- a/apps/start/src/components/chat/chat-drawer.tsx
+++ b/apps/start/src/components/chat/chat-drawer.tsx
@@ -1,4 +1,3 @@
-import { useAppContext } from '@/hooks/use-app-context';
import { useAppParams } from '@/hooks/use-app-params';
import { useResizableDrawer } from '@/hooks/use-resizable-drawer';
import { useEffect } from 'react';
@@ -27,9 +26,14 @@ const MAX_WIDTH = 720;
*/
export function ChatDrawer() {
const { projectId } = useAppParams();
- const { isAiEnabled } = useAppContext();
- const { agentName, conversationId, isOpen, closeChat, openChatForContext } =
- useChatState();
+ const {
+ agentName,
+ conversationId,
+ isOpen,
+ isAiEnabled,
+ closeChat,
+ openChatForContext,
+ } = useChatState();
const { width, dragHandleProps } = useResizableDrawer({
defaultWidth: DEFAULT_WIDTH,
minWidth: MIN_WIDTH,
@@ -83,18 +87,20 @@ export function ChatDrawer() {
/>
<ChatDrawerHeader projectId={projectId} onClose={closeChat} />
{/*
- Three states here:
- 1. `!isAiEnabled` — neither `OPENAI_API_KEY` nor
- `ANTHROPIC_API_KEY` is set on the API. Skip the runtime
- entirely and render the setup-instructions empty state.
- 2. `isAiEnabled` but `agentName` is still empty — the
- `trpc.chat.models` query is in flight. Render a brief
- placeholder so we don't crash `useAgent({ agent: '' })`.
+ Three states, all derived from the `chat.models` tRPC query
+ (see `ChatStateProvider`). The frontend no longer reads any
+ AI-specific env vars — empty models list = not configured.
+ 1. `isAiEnabled === false` — the API returned zero models,
+ meaning no provider keys are set. Skip the runtime and
+ render the setup-instructions empty state.
+ 2. `isAiEnabled` is `null` or `agentName` is still empty —
+ models query in flight. Render a placeholder so we don't
+ crash `useAgent({ agent: '' })`.
3. `agentName` resolved — mount the runtime as normal.
`key={conversationId}` remounts the `useAgent` controller
on conversation switches to force a fresh hydrate.
*/}
- {!isAiEnabled ? (
+ {isAiEnabled === false ? (
<ChatDrawerNotConfigured />
) : agentName ? (
<ChatRuntimeProvider key={conversationId}>
diff --git a/apps/start/src/components/chat/tool-results/output-types.ts b/apps/start/src/components/chat/tool-results/output-types.ts
index 0972cead0..a8209dbcc 100644
--- a/apps/start/src/components/chat/tool-results/output-types.ts
+++ b/apps/start/src/components/chat/tool-results/output-types.ts
@@ -98,8 +98,14 @@ export type TableNormalized = {
/**
* Several tools return either an array directly or wrap it in `{ rows }`,
- * `{ data }`, or `{ opportunities }`. This is the one place where we
- * resolve that — every renderer downstream gets a clean `TableRow[]`.
+ * `{ data }`, `{ opportunities }`, or `{ properties }`. This is the one
+ * place where we resolve that — every renderer downstream gets a clean
+ * `TableRow[]`.
+ *
+ * `properties` covers `list_event_properties` / `list_properties_for_event`,
+ * which return a flat `string[]` of property keys after the server rolled
+ * up dotted sub-keys. We lift each into `{ property_key }` so the generic
+ * table renderer can pick it up as the label column.
*/
export function normalizeTableOutput(value: unknown): TableNormalized {
if (Array.isArray(value)) {
@@ -122,6 +128,12 @@ export function normalizeTableOutput(value: unknown): TableNormalized {
if (Array.isArray(o.opportunities)) {
return { rows: o.opportunities as TableRow[], total, truncated };
}
+ if (Array.isArray(o.properties)) {
+ const rows: TableRow[] = (o.properties as unknown[]).map((p) =>
+ typeof p === 'string' ? { property_key: p } : (p as TableRow),
+ );
+ return { rows, total, truncated };
+ }
}
return { rows: [], total: undefined, truncated: false };
}
diff --git a/apps/start/src/hooks/use-app-context.ts b/apps/start/src/hooks/use-app-context.ts
index b36030598..b01c6123d 100644
--- a/apps/start/src/hooks/use-app-context.ts
+++ b/apps/start/src/hooks/use-app-context.ts
@@ -18,6 +18,5 @@ export function useAppContext() {
isSelfHosted: params.isSelfHosted,
isMaintenance: params.isMaintenance ?? false,
isDemo: params.isDemo ?? false,
- isAiEnabled: params.isAiEnabled ?? false,
};
}
diff --git a/apps/start/src/routes/api/config.tsx b/apps/start/src/routes/api/config.tsx
index 508348d01..0b1b1d08a 100644
--- a/apps/start/src/routes/api/config.tsx
+++ b/apps/start/src/routes/api/config.tsx
@@ -7,7 +7,6 @@ export interface ConfigResonse {
isSelfHosted: boolean;
isMaintenance: boolean;
isDemo: boolean;
- isAiEnabled: boolean;
}
// Nothing sensitive here, its client environment variables which is good for debugging
export const Route = createFileRoute('/api/config')({
diff --git a/apps/start/src/server/get-envs.ts b/apps/start/src/server/get-envs.ts
index 26f7cc0fb..f1202c096 100644
--- a/apps/start/src/server/get-envs.ts
+++ b/apps/start/src/server/get-envs.ts
@@ -10,9 +10,6 @@ export const getServerEnvs = createServerFn().handler(() => {
isSelfHosted: process.env.SELF_HOSTED !== undefined,
isMaintenance: process.env.MAINTENANCE === '1',
isDemo: process.env.DEMO_USER_ID !== undefined,
- isAiEnabled: Boolean(
- process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY,
- ),
};
return envs;
diff --git a/packages/trpc/src/routers/chat.ts b/packages/trpc/src/routers/chat.ts
index 9228934f2..58f226524 100644
--- a/packages/trpc/src/routers/chat.ts
+++ b/packages/trpc/src/routers/chat.ts
@@ -1,4 +1,7 @@
-import { getAvailableChatModels } from '@openpanel/validation';
+import {
+ getAvailableChatModels,
+ PREFERRED_DEFAULT_MODEL_ID,
+} from '@openpanel/validation';
import { createTRPCRouter, protectedProcedure } from '../trpc';
@@ -17,10 +20,12 @@ export const chatRouter = createTRPCRouter({
anthropic: Boolean(process.env.ANTHROPIC_API_KEY),
};
const models = getAvailableChatModels(providers);
+ const preferred = models.find((m) => m.id === PREFERRED_DEFAULT_MODEL_ID);
+ const defaultModelId = preferred?.id ?? models[0]?.id ?? null;
return {
providers,
models,
- defaultModelId: models[0]?.id ?? null,
+ defaultModelId,
};
}),
});
diff --git a/packages/validation/src/chat.ts b/packages/validation/src/chat.ts
index b890f89b7..46df06808 100644
--- a/packages/validation/src/chat.ts
+++ b/packages/validation/src/chat.ts
@@ -142,7 +142,27 @@ export const CHAT_MODELS = [
export type ChatModelId = (typeof CHAT_MODELS)[number]['id'];
-export const MODEL_STORAGE_KEY = 'op-chat-model';
+/**
+ * localStorage key holding the user's preferred chat model id.
+ *
+ * Bumped to `v2` when the default was switched from `gpt-4-1` to
+ * `gpt-4-1-mini` (April 2026). Existing users had `gpt-4-1` pinned in
+ * their v1 key and hit rate-limit errors almost immediately on Tier 1
+ * OpenAI accounts; invalidating the old key is the only way to
+ * migrate them to the new default without a UI prompt. If you change
+ * the default again, bump the suffix.
+ */
+export const MODEL_STORAGE_KEY = 'op-chat-model-v2';
+
+/**
+ * Preferred default model id. The tRPC `chat.models` endpoint picks
+ * this when it's available in the configured provider set, falling
+ * back to the first entry in `CHAT_MODELS` otherwise. Picked for its
+ * much higher per-minute token budget (OpenAI Tier 1 gives gpt-4.1
+ * just 30k TPM — one user exhausts it with a single long turn —
+ * whereas gpt-4.1-mini gets 200k TPM for the same tier).
+ */
+export const PREFERRED_DEFAULT_MODEL_ID = 'gpt-4-1-mini';
export function isValidModelId(id: string | null | undefined): id is ChatModelId {
return !!id && CHAT_MODELS.some((m) => m.id === id);