86 lines
4.1 KiB
Markdown
86 lines
4.1 KiB
Markdown
|
---
|
||
|
|
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).
|