---
id: SEED-003
status: dormant
planted: 2026-07-10
planted_during: v1.0 milestone (Pulse Mobile Shell Redesign), Phase 9.1 in flight
trigger_when: After PAX8 (SEED-002) and ideally other core data sources are mirrored into Postgres — surface during the next /gsd-new-milestone scan
scope: Large
---

# SEED-003: General Pulse Data Assistant

A natural-language chatbot interface over Pulse's own data generally — tickets,
companies, engagement, finance, and PAX8 once it exists — not scoped to any
single integration.

## Why This Matters

Surfaced while scoping [[SEED-002]] (PAX8 integration): the developer wants
"the ability to ask questions through a chatbot style interface" as one of the
motivations for pulling PAX8 data in, but on reflection the real want is broader
than PAX8 — a general assistant that happens to need PAX8 (and other sources)
as data it can draw on, not a PAX8-specific bot.

This is a meaningfully different initiative from any single data integration:
it needs a query/tool-calling layer that can span multiple Postgres tables
safely, decide what's answerable, and present results — not just sync data
into a table.

## When to Surface

**Trigger:** After PAX8 data (SEED-002) — and ideally other core sources
(tickets, engagement, finance) — are mirrored into Postgres and stable. Also
surface if a future milestone's scope mentions: "chatbot", "natural language
query", "ask Pulse", "data assistant", or "LLM interface over dashboard data".

## Scope Estimate

**Large** — likely its own multi-phase milestone. Needs: query/tool-calling
architecture (what can the LLM call — raw SQL? scoped read helpers per domain?),
guardrails against unsafe/expensive queries, a chat UI surface (new page, or a
persistent widget across pages?), conversation state/history, and an answer
format that handles tabular results well (not just prose).

## Breadcrumbs

- Existing LLM plumbing to reuse rather than rebuild: `@anthropic-ai/sdk`
  already wired for the AI Ticket Analyzer pipeline
  (`lib/services/analyzer/pipeline.ts`, `lib/services/analyzer/stages/*.ts`),
  plus `ai-triage-service.ts`. Provider is per-request (`anthropic` |
  `openrouter`) — same pattern likely applies here.
- Analyzer's cost-ceiling guard (Stage 4 skipped above $2.00 estimated cost) is
  a pattern worth mirroring for a chat interface that could otherwise run
  unbounded queries/tokens per question.
- IT Glue data has a hard redaction requirement before hitting an LLM
  (`lib/services/analyzer/itglue-search.ts`) — any assistant that can see IT
  Glue-sourced data must route through the same redaction, not raw client
  output.
- `postgresClient` singleton (`lib/services/postgres-client.ts`) is the only
  DB access path — any tool-calling layer built for this assistant should call
  through it, not open a second connection path.
- Data sources this assistant should eventually reach: tickets (Autotask sync),
  companies, engagement snapshots (`engagement_snapshots`), finance/QBO data,
  and PAX8 once [[SEED-002]] lands.

## Notes

### Key design forks (decide during brainstorming, not now)
- **Tool-calling over scoped read helpers vs. raw SQL generation** — raw
  text-to-SQL is riskier (injection, runaway queries, schema drift); scoped
  helpers per domain (e.g. `getCompanySubscriptionCosts(companyId)`) are safer
  but need maintenance as new questions come up. Current lean: scoped helpers,
  mirroring the analyzer's structured-stage-output philosophy.
- **Where it surfaces** — dedicated page vs. a persistent chat widget
  available across desktop and mobile. Not decided.
- **Read-only vs. can it trigger actions** — e.g. could it kick off a sync, or
  strictly answer questions? Current lean: read-only, at least for v1.
- **Conversation memory** — single-turn Q&A vs. multi-turn session with
  history. Affects whether this needs new schema (a `chat_sessions` /
  `chat_messages` table) beyond the query layer itself.

### Anti-goals
- Not a replacement for the existing dashboards/pages — a supplement for
  ad-hoc questions those views don't answer directly.
- Not scoped to any single integration (started life as a "PAX8 chatbot" idea,
  deliberately broadened).