mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-07-06 22:12:12 +02:00
docs(revamp): rename primitive to Tracker, subagent to intelligence_agent
This commit is contained in:
CREDO23
parent
3aeecc315a
commit
d5df87dafd
6 changed files with 70 additions and 71 deletions
|
|
@ -12,7 +12,7 @@ PRODUCT A — stateless utility ① Capabilities + ② Access
|
|||
call a verb → get data → bill. Nothing persists.
|
||||
|
||||
PRODUCT B — decision-grounded CI ③ Intelligence + ④ Timeline (+ ⑤ Triggers to drive it)
|
||||
a Lens accumulates structured signal over time. The Timeline is the moat.
|
||||
a Tracker accumulates structured signal over time. The Timeline is the moat.
|
||||
```
|
||||
|
||||
## The domain map
|
||||
|
|
@ -22,7 +22,7 @@ PRODUCT B — decision-grounded CI ③ Intelligence + ④ Timeline (+ ⑤ Tri
|
|||
┌─────────────────────────────────┐ ┌──────────────────────────────────────────────┐
|
||||
│ Acquisition │ │ ① Capabilities typed verbs over Acquisition │
|
||||
│ proprietary/web_crawler │◄──┤ ② Access chat · REST · MCP doors │
|
||||
│ CrawlOutcome · billing (03c) │ │ ③ Intelligence Lens · schema · hot loop │
|
||||
│ CrawlOutcome · billing (03c) │ │ ③ Intelligence Tracker · schema · hot loop │
|
||||
│ │ │ ④ Timeline 3-store delta state (moat) │
|
||||
│ │ │ ⑤ Triggers pluggable refresh clock │
|
||||
│ │ │ ⑥ Orchestration CI-expert subagent + tools │
|
||||
|
|
@ -34,10 +34,10 @@ PRODUCT B — decision-grounded CI ③ Intelligence + ④ Timeline (+ ⑤ Tri
|
|||
|---|--------|----------|-----|
|
||||
| ① | Capabilities | Acquisition → typed callable verbs (`web.scrape`, `web.discover`, `maps.*`) | `01-capabilities.md` |
|
||||
| ② | Access | expose verbs to callers, authed + metered (chat / REST / MCP) | `02-access.md` |
|
||||
| ③ | Intelligence | the Lens, agent-designed locked schema, hot loop (agent judges, code computes) | `03-intelligence.md` |
|
||||
| ③ | Intelligence | the Tracker, agent-designed locked schema, hot loop (agent judges, code computes) | `03-intelligence.md` |
|
||||
| ④ | Timeline | durable time-shaped truth; deltas not snapshots; no change → no row | `04-timeline.md` |
|
||||
| ⑤ | Triggers | when a Lens refreshes; `refresh(lens)` callers; recurrence+delivery = optional CI action on automations | `05-triggers.md` |
|
||||
| ⑥ | Orchestration | the human-facing CI-expert subagent (intent routing, verb chains, Lens crafting) + its tools | `06-orchestration.md` |
|
||||
| ⑤ | Triggers | when a Tracker refreshes; `refresh(tracker)` callers; recurrence+delivery = optional CI action on automations | `05-triggers.md` |
|
||||
| ⑥ | Orchestration | the human-facing CI-expert subagent (intent routing, verb chains, Tracker crafting) + its tools | `06-orchestration.md` |
|
||||
|
||||
## Reconciliation with the old plans
|
||||
|
||||
|
|
@ -45,7 +45,7 @@ PRODUCT B — decision-grounded CI ③ Intelligence + ④ Timeline (+ ⑤ Tri
|
|||
|----------|------|---------------|
|
||||
| `04a-connector-category.md` | **demoted to hygiene** | the genuine MCP-routing fix survives in ② (consume-user-MCP); the taxonomy work is not core |
|
||||
| `04b-source-discovery.md` | **absorbed** | becomes the `web.discover` capability in ① |
|
||||
| `05-pipelines-model.md` | **dissolved** | the "pipeline" concept → the `Lens` (③) + Timeline tables (④); no `pipeline`/`pipeline_runs` |
|
||||
| `05-pipelines-model.md` | **dissolved** | the "pipeline" concept → the `Tracker` (③) + Timeline tables (④); no `pipeline`/`pipeline_runs` |
|
||||
| `06-pipelines-exec.md` | **dissolved** | execution → the hot loop (③); scheduling/runs/delivery → **reuse automations** via a CI action (⑤) — its selector + `AutomationRun`, **not** a rebuilt cron |
|
||||
| `07-upload-pipeline-kb.md` | **dropped (crawl→KB + uploads-as-pipeline audit)** | "don't index *crawled* data" holds. **User file-upload-to-KB remains a pre-existing, untouched feature** (uploads still become indexed KB Documents). For CI, uploads are routed to a dedicated **folder** and may feed the judge (`03`, F) |
|
||||
|
||||
|
|
@ -60,16 +60,16 @@ out; *user uploads* still work (and gain a CI context-folder role).
|
|||
4. **③ Intelligence** — schema-design agent + hot loop + materiality evaluator.
|
||||
5. **⑤ Triggers** — manual/agent/external-cron; then the CI **automation action** (recurrence +
|
||||
delivery) reusing the automations selector + `AutomationRun`.
|
||||
6. **⑥ Orchestration** — the `analyst` CI-expert subagent + tools + prompt (the human-facing seam;
|
||||
6. **⑥ Orchestration** — the `intelligence_agent` CI-expert subagent + tools + prompt (the human-facing seam;
|
||||
built atop ①–④, can grow alongside them).
|
||||
|
||||
## Consolidated open forks (need your call)
|
||||
|
||||
1. Primitive **name** — using `Lens` as a working label; confirm or replace.
|
||||
2. Schema **review-&-lock** UX before frontend exists — pure-chat confirmation for MVP?
|
||||
3. Timeline ORM home — `app/db.py` vs dedicated `app/timeline/`.
|
||||
4. Recurrence = CI **action** on automations (default) vs a thin CI automation **shape** (fallback).
|
||||
1. Schema **review-&-lock** UX before frontend exists — pure-chat confirmation for MVP?
|
||||
2. Timeline ORM home — `app/db.py` vs dedicated `app/timeline/`.
|
||||
3. Recurrence = CI **action** on automations (default) vs a thin CI automation **shape** (fallback).
|
||||
|
||||
*(Resolved: primitive **name** = `Tracker`, subagent = `intelligence_agent` (Intelligence Agent).)*
|
||||
*(Resolved: the "built-in scheduler tick" fork — we reuse the automations schedule selector via a CI
|
||||
action instead of building a tick. See `05`.)*
|
||||
|
||||
|
|
@ -84,10 +84,10 @@ action instead of building a tick. See `05`.)*
|
|||
- **Don't index** crawled data into the KB; the Timeline (deltas) is the only persisted CI state.
|
||||
- CI is **decoupled from automations** (automations = one optional Trigger adapter).
|
||||
- Intelligence: **agent-designed schema** (sample-grounded, human-locked, versioned) in MVP; single
|
||||
entity per Lens; materiality = code thresholds (numeric/clear) + agent on ambiguous; content-hash
|
||||
entity per Tracker; materiality = code thresholds (numeric/clear) + agent on ambiguous; content-hash
|
||||
pre-check before LLM spend.
|
||||
- Orchestration is a first-class deliverable: a **net-new CI-expert subagent** (`analyst`, working
|
||||
name) on the existing chat runtime, with registry-backed verb tools + Lens/Timeline tools; intent
|
||||
- Orchestration is a first-class deliverable: a **net-new CI-expert subagent** (`intelligence_agent`, working
|
||||
name) on the existing chat runtime, with registry-backed verb tools + Tracker/Timeline tools; intent
|
||||
routing lives in its prompt, the headless logic stays in ③/④.
|
||||
- **Recurrence + alert delivery = a CI *action* on the existing automations** (not a new scheduler,
|
||||
not a new shape): reuses the hardened schedule selector, `AutomationRun` (audit + idempotency), and
|
||||
|
|
|
|||
|
|
@ -60,12 +60,12 @@ user never has to:
|
|||
|
||||
```
|
||||
"compare / find / what is / pull / summarize / right now" → ONE-SHOT → call verbs, answer (Product A, stateless)
|
||||
"watch / track / notify me when / every week / keep an eye / over time" → STANDING → start the Lens setup flow (Product B, stateful → ③)
|
||||
"watch / track / notify me when / every week / keep an eye / over time" → STANDING → start the Tracker setup flow (Product B, stateful → ③)
|
||||
```
|
||||
|
||||
- **One-shot** → orchestrate verbs now, synthesize an answer; nothing persists beyond chat.
|
||||
- **Standing concern** → hand off to the Intelligence setup flow (`03`): sample-fetch → agent proposes
|
||||
schema/thresholds/identity → user validates & locks → Lens runs on a trigger.
|
||||
schema/thresholds/identity → user validates & locks → Tracker runs on a trigger.
|
||||
- **Ambiguous** → ask exactly **one** clarifying question — *"just this once, or should I keep watching
|
||||
it for you?"* — which is the entire A-vs-B decision expressed in human terms.
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
> **WIP design doc.** Part of the Phase 4 → end revamp. Pairs with `04-timeline.md` (the state it writes).
|
||||
> **Scope guardrail:** Phases 1–3 SHIPPED/FIXED. This is net-new and is **not** the KB and **not**
|
||||
> the automations subsystem.
|
||||
> **Working name:** the standing-concern primitive is called a **Lens** (provisional — easily renamed).
|
||||
> **Name:** the standing-concern primitive is the **Tracker**.
|
||||
|
||||
## The stateless / stateful line
|
||||
|
||||
|
|
@ -20,7 +20,7 @@ below the Access→Intelligence boundary stays pure functions.
|
|||
Turn repeated capability calls into **decision-relevant structured signal**. The motto: **the agent
|
||||
judges, code computes.** This replaces the old "pipeline" as the *standing concern*.
|
||||
|
||||
## The primitive — `Lens`
|
||||
## The primitive — `Tracker`
|
||||
|
||||
A saved, decision-grounded subject that accumulates structured signal over time:
|
||||
|
||||
|
|
@ -31,7 +31,7 @@ A saved, decision-grounded subject that accumulates structured signal over time:
|
|||
| `definition` (locked, versioned) | `{ field_schema, identity_rule, materiality }` — the agent-drafted, human-locked contract |
|
||||
| `status` | `draft` → `locked`/`active` |
|
||||
|
||||
One **entity per Lens for MVP** (one place / one URL). Multi-entity (`maps.search → many`) is deferred
|
||||
One **entity per Tracker for MVP** (one place / one URL). Multi-entity (`maps.search → many`) is deferred
|
||||
(the Timeline model stays multi-entity-ready so it's additive).
|
||||
|
||||
## Setup (once) — the agent-designed schema flow (IN MVP)
|
||||
|
|
@ -52,7 +52,7 @@ no UI needed):
|
|||
5. **Versioned** — a locked `definition` is a snapshot; edits create a new version (mirrors how
|
||||
`automations` snapshots `definition`).
|
||||
|
||||
## The hot loop (per refresh) — `refresh(lens)`
|
||||
## The hot loop (per refresh) — `refresh(tracker)`
|
||||
|
||||
1. **Crawl** — call the bound capability (Domain ①) → raw data.
|
||||
2. **Cheap pre-check** — content hash via the existing
|
||||
|
|
@ -84,12 +84,12 @@ description reworded → code: no rule → ASK AGENT → NOISE
|
|||
|
||||
- New **Apache-2** package `app/intelligence/` (the schema-design agent, the hot loop, the materiality
|
||||
evaluator). Calls capability `executor`s directly (not through a door).
|
||||
- Exposes **`refresh(lens)`**. *Who* calls it (manual / agent / external cron / optional automation) is
|
||||
- Exposes **`refresh(tracker)`**. *Who* calls it (manual / agent / external cron / optional automation) is
|
||||
the **Triggers** domain's concern — Intelligence has **no dependency** on any scheduler.
|
||||
|
||||
## Refresh execution & idempotency — ride the invoking surface (no new run table)
|
||||
|
||||
`refresh(lens)` is a **headless unit of work**; the **run/audit record + idempotency live on whatever
|
||||
`refresh(tracker)` is a **headless unit of work**; the **run/audit record + idempotency live on whatever
|
||||
surface invoked it**, so we do *not* rebuild old Phase-6 `pipeline_runs`:
|
||||
|
||||
- **Recurring (in-app):** invoked by the **CI automation action** (`05`) → the existing
|
||||
|
|
@ -112,7 +112,7 @@ into the **KB as normal** — uploads create `Document`s and are indexed/embedde
|
|||
**(The "don't index" rule applies only to *crawled* data, not to user uploads.)** The CI-specific part
|
||||
is purely **organization + use**:
|
||||
|
||||
- **Routed to a dedicated folder** for that CI chat/Lens (reuse the existing folder-upload /
|
||||
- **Routed to a dedicated folder** for that CI chat/Tracker (reuse the existing folder-upload /
|
||||
`destination_folder` machinery), so the chat's reference files are scoped together.
|
||||
- **The judge step (5) may consult them** — retrieved from the KB, scoped to that folder — when ruling
|
||||
materiality:
|
||||
|
|
@ -129,21 +129,21 @@ works without it); design the seam now so the judge can read the folder later.
|
|||
## MVP cut vs north star
|
||||
|
||||
- **MVP:** agent-designed-schema flow (conversational, sample-grounded, human-locked) · single entity
|
||||
per Lens · the hot loop with content-hash pre-check + code-threshold + agent-on-ambiguous ·
|
||||
`refresh(lens)` fired manually / by agent / by external cron.
|
||||
per Tracker · the hot loop with content-hash pre-check + code-threshold + agent-on-ambiguous ·
|
||||
`refresh(tracker)` fired manually / by agent / by external cron.
|
||||
- **North star (deferred):** schema **auto-evolution** from recurring `notable_signals` · multi-entity
|
||||
Lenses (`maps.search`) · backward-replay reconstruction · coverage-confidence · full
|
||||
Trackers (`maps.search`) · backward-replay reconstruction · coverage-confidence · full
|
||||
provenance/explainability · the resale/data-product stage.
|
||||
|
||||
## Locked decisions
|
||||
|
||||
1. `Lens` (provisional name) is the standing-concern primitive; replaces "pipeline".
|
||||
1. `Tracker` is the standing-concern primitive; replaces "pipeline".
|
||||
2. Stateless (①②/Product A) vs stateful (③④/Product B) is the Access→Intelligence boundary.
|
||||
3. **Agent-designed schema flow is in MVP** (not hand-authored) — sample-grounded, human-locked, versioned.
|
||||
4. Single entity per Lens for MVP.
|
||||
4. Single entity per Tracker for MVP.
|
||||
5. Materiality = deterministic numeric/clear rules in code + agent only on ambiguous.
|
||||
6. Content-hash pre-check short-circuits unchanged pages before any LLM spend.
|
||||
7. `app/intelligence/` Apache-2; `refresh(lens)` is trigger-agnostic.
|
||||
7. `app/intelligence/` Apache-2; `refresh(tracker)` is trigger-agnostic.
|
||||
8. **No new run table** — refresh audit/idempotency ride `AutomationRun` (recurring) or the chat job
|
||||
record; billing idempotency is per-capability-call + the content-hash gate. Only Timeline (`04`) is
|
||||
new state.
|
||||
|
|
@ -157,4 +157,4 @@ works without it); design the seam now so the judge can read the folder later.
|
|||
confirmation for MVP?).
|
||||
- Versioning policy on re-lock (new version vs in-place) — lean new version.
|
||||
- Where the schema-design agent itself runs (a setup capability? a chat sub-flow?).
|
||||
- Context-folder → judge wiring (how much of the folder to load; per-Lens vs per-chat scope).
|
||||
- Context-folder → judge wiring (how much of the folder to load; per-Tracker vs per-chat scope).
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@
|
|||
|
||||
## Purpose
|
||||
|
||||
Durably store the **time-shaped truth** for each Lens. This is the asset: **time is the moat** —
|
||||
Durably store the **time-shaped truth** for each Tracker. This is the asset: **time is the moat** —
|
||||
accumulated history a later entrant cannot re-create. Design rule: **store deltas, not snapshots —
|
||||
no change, no row.** Storage grows with the *rate of change*, not the number of runs.
|
||||
|
||||
|
|
@ -21,7 +21,7 @@ without running the loop**. That separation is the reason Timeline is its own do
|
|||
|
||||
| Store | Role | Write pattern |
|
||||
|-------|------|---------------|
|
||||
| `tracked_entities` | stable identity per tracked thing (the Lens's `identity_rule` → `entity_key`) | written **once** |
|
||||
| `tracked_entities` | stable identity per tracked thing (the Tracker's `identity_rule` → `entity_key`) | written **once** |
|
||||
| `entity_current_state` | latest values + `content_hash` + `last_checked_at` per entity | **overwritten** each run |
|
||||
| `entity_changes` (the change log) | append-only material deltas | **appended**, never overwritten |
|
||||
|
||||
|
|
@ -32,16 +32,16 @@ replay deltas backward (north-star tooling; not built in MVP — we just *store*
|
|||
|
||||
```
|
||||
tracked_entities
|
||||
id · workspace_id · lens_id (FK) · entity_key (unique per lens) · first_seen_at
|
||||
# MVP: exactly one row per Lens (single-entity). Table stays multi-entity-ready.
|
||||
id · workspace_id · tracker_id (FK) · entity_key (unique per tracker) · first_seen_at
|
||||
# MVP: exactly one row per Tracker (single-entity). Table stays multi-entity-ready.
|
||||
|
||||
entity_current_state
|
||||
entity_id (FK, unique) · lens_id · fields JSONB (latest, conforms to locked field_schema)
|
||||
entity_id (FK, unique) · tracker_id · fields JSONB (latest, conforms to locked field_schema)
|
||||
· content_hash · last_checked_at · updated_at
|
||||
# overwritten each material run; content_hash powers the hot-loop cheap pre-check (03 step 2)
|
||||
|
||||
entity_changes # the append-only change log
|
||||
id · entity_id (FK) · lens_id · captured_at
|
||||
id · entity_id (FK) · tracker_id · captured_at
|
||||
· delta JSONB # { field: { from, to } }
|
||||
· materiality # material | notable(=notable_signals-sourced)
|
||||
· decided_by # code | agent (audit of the materiality split)
|
||||
|
|
@ -70,7 +70,7 @@ entity_changes # the append-only change log
|
|||
|
||||
## MVP cut vs north star
|
||||
|
||||
- **MVP:** the three stores · single entity per Lens · deltas with `decided_by`/`source_ref` ·
|
||||
- **MVP:** the three stores · single entity per Tracker · deltas with `decided_by`/`source_ref` ·
|
||||
`content_hash` pre-check support.
|
||||
- **North star (deferred):** backward-replay reconstruction queries · trend/series read APIs ·
|
||||
coverage-confidence metadata · multi-entity scale · the resale/data-product surface.
|
||||
|
|
@ -82,11 +82,11 @@ entity_changes # the append-only change log
|
|||
3. CI-owned new tables; **not** KB, **not** `automation_runs`.
|
||||
4. `content_hash` on current state powers the hot-loop cheap pre-check.
|
||||
5. `decided_by` on changes records the code-vs-agent materiality provenance.
|
||||
6. Single entity per Lens for MVP; schema stays multi-entity-ready (additive later).
|
||||
6. Single entity per Tracker for MVP; schema stays multi-entity-ready (additive later).
|
||||
|
||||
## Open questions (carry forward)
|
||||
|
||||
- ORM home: `app/db.py` vs a dedicated `app/timeline/` package.
|
||||
- Whether `entity_current_state.fields` should be validated against the Lens's locked `field_schema`
|
||||
- Whether `entity_current_state.fields` should be validated against the Tracker's locked `field_schema`
|
||||
at write time (lean: yes, cheap integrity guard).
|
||||
- Retention / archival policy for very high-velocity entities (deferred).
|
||||
|
|
|
|||
|
|
@ -6,13 +6,13 @@
|
|||
|
||||
## Purpose
|
||||
|
||||
Decide **when** a Lens refreshes. Intelligence exposes a single entry point — **`refresh(lens)`** —
|
||||
Decide **when** a Tracker refreshes. Intelligence exposes a single entry point — **`refresh(tracker)`** —
|
||||
and every trigger is just a caller. Intelligence never knows which trigger fired; remove any trigger
|
||||
and the engine still works.
|
||||
|
||||
This replaces Phase 6's cron scheduler — and the resolution is **not** to rebuild a scheduler at all,
|
||||
but to **reuse the automations subsystem** for the in-app recurring path (it already has a hardened
|
||||
clock + run record + delivery). A trigger only ever calls `refresh(lens)`.
|
||||
clock + run record + delivery). A trigger only ever calls `refresh(tracker)`.
|
||||
|
||||
## The adapters
|
||||
|
||||
|
|
@ -20,8 +20,8 @@ clock + run record + delivery). A trigger only ever calls `refresh(lens)`.
|
|||
|---------|----------|------|
|
||||
| **Manual** | user "refresh now" (chat tool / REST) | ✅ |
|
||||
| **Agent** | the in-app agent calls `refresh` as a tool | ✅ |
|
||||
| **External cron** | the user's own scheduler hits `POST /v1/lenses/{id}/refresh` | ✅ (zero infra on us) |
|
||||
| **CI automation action** | a **CI action on the existing automations** — its schedule trigger fires `refresh(lens)` **and delivers** the material changes | ✅ (the in-app recurrence + alert path) |
|
||||
| **External cron** | the user's own scheduler hits `POST /v1/trackers/{id}/refresh` | ✅ (zero infra on us) |
|
||||
| **CI automation action** | a **CI action on the existing automations** — its schedule trigger fires `refresh(tracker)` **and delivers** the material changes | ✅ (the in-app recurrence + alert path) |
|
||||
|
||||
## Recurrence + delivery — a CI action on existing automations (NOT a new scheduler, NOT a new shape)
|
||||
|
||||
|
|
@ -38,25 +38,25 @@ to the existing automations subsystem**:
|
|||
the user. **(closes the old Gap E — alert delivery.)**
|
||||
|
||||
**Why a CI *action*, not a new automation shape:** a new shape would duplicate triggers, runs, and
|
||||
delivery that already exist. A single `refresh_lens` action reuses all of it. (If implementation finds
|
||||
delivery that already exist. A single `refresh_tracker` action reuses all of it. (If implementation finds
|
||||
the action too constraining, a thin CI-specific shape is the fallback — but the action is the default.)
|
||||
|
||||
### Decoupling is preserved (automations is still optional)
|
||||
|
||||
CI **core** — `refresh(lens)` + Timeline (`03`/`04`) — has **zero** automations dependency and runs via
|
||||
CI **core** — `refresh(tracker)` + Timeline (`03`/`04`) — has **zero** automations dependency and runs via
|
||||
manual / agent / external-cron. Automations is the **optional adapter** that adds recurrence + delivery
|
||||
+ audit for in-app users. So we honor "don't glue CI to automations" *and* get its machinery for free.
|
||||
|
||||
## Where it lives / decoupling
|
||||
|
||||
- The **CI action** lives with automations (its action registry); it imports `refresh(lens)` from
|
||||
- The **CI action** lives with automations (its action registry); it imports `refresh(tracker)` from
|
||||
`app/intelligence/`. No new scheduler/Beat task.
|
||||
- The **external-cron** and **REST manual** paths are just Access-door routes (`POST
|
||||
/v1/lenses/{id}/refresh`) — Domain ② plumbing.
|
||||
/v1/trackers/{id}/refresh`) — Domain ② plumbing.
|
||||
|
||||
## Locked decisions
|
||||
|
||||
1. Intelligence exposes `refresh(lens)`; all triggers are callers. Fully decoupled.
|
||||
1. Intelligence exposes `refresh(tracker)`; all triggers are callers. Fully decoupled.
|
||||
2. Adapters: manual · agent · external-cron · **CI automation action** (recurrence + delivery).
|
||||
3. **No bespoke scheduler and no new run table** — the recurring path reuses the automations schedule
|
||||
selector + `AutomationRun`; delivery reuses automations' output. (Closes old Gaps A/B/E.)
|
||||
|
|
@ -68,5 +68,5 @@ manual / agent / external-cron. Automations is the **optional adapter** that add
|
|||
- CI **action** vs a thin CI-specific automation **shape** (default: action; shape is the fallback).
|
||||
- What the delivered payload looks like (the material `entity_changes` since last fire — summarized by
|
||||
the agent, or raw deltas).
|
||||
- Concurrency: skip a refresh if the Lens already has one in flight (per-Lens lock, like the connector
|
||||
- Concurrency: skip a refresh if the Tracker already has one in flight (per-Tracker lock, like the connector
|
||||
indexing lock) — even with the automation run-gate, belt-and-suspenders.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
|
||||
## Why this is a first-class deliverable
|
||||
|
||||
The intent router + verb-composition + Lens-crafting are where "user-friendly" is won or lost. Treating
|
||||
The intent router + verb-composition + Tracker-crafting are where "user-friendly" is won or lost. Treating
|
||||
the agent prompt/tooling as plumbing would make the product feel rigid. So the orchestration layer gets
|
||||
designed, not assumed.
|
||||
|
||||
|
|
@ -27,9 +27,9 @@ billing** shape: it calls `WebCrawlerConnector.crawl_url`, bills via the turn ac
|
|||
(`get_current_accumulator()` + `WebCrawlCreditService`), returns a typed dict. Our capability/CI tools
|
||||
follow this exactly.
|
||||
|
||||
## What's new — the `analyst` subagent (CI expert)
|
||||
## What's new — the `intelligence_agent` subagent (CI expert)
|
||||
|
||||
A new builtin `subagents/builtins/analyst/` (working name — the competitive-intelligence specialist),
|
||||
A new builtin `subagents/builtins/intelligence_agent/` (the competitive-intelligence specialist),
|
||||
peer to `research`/`deliverables`. The **main agent delegates** to it whenever the request is
|
||||
CI-flavored (research a competitor, watch something, analyze a place's reviews); `description.md` is
|
||||
what makes that routing happen.
|
||||
|
|
@ -41,7 +41,7 @@ It owns the **CI playbook** in `system_prompt.md`:
|
|||
ambiguous → ask the single clarifying question.
|
||||
2. **Verb composition** — the chains: `web.discover → web.scrape`, `maps.search → maps.place →
|
||||
maps.reviews`; infer URLs/queries/locations from context so the user never supplies them by hand.
|
||||
3. **Lens crafting** (the "crafting" you flagged) — the conversational schema-design flow from `03`:
|
||||
3. **Tracker crafting** (the "crafting" you flagged) — the conversational schema-design flow from `03`:
|
||||
sample-fetch → propose `field_schema` + materiality + identity → user validates & locks → versioned.
|
||||
4. **Decision-grounded answering** — read the Timeline (`04`) to answer "what changed / is X pulling
|
||||
ahead?" from stored deltas, not by re-deriving from chat history.
|
||||
|
|
@ -51,21 +51,21 @@ It owns the **CI playbook** in `system_prompt.md`:
|
|||
| Tool | Wraps | Mode | Billing |
|
||||
|------|-------|------|---------|
|
||||
| capability verbs (`web.scrape`, `web.discover`, `maps.search`, `maps.place`, `maps.reviews`) | Domain ① executors | inline-or-job (slow → `deliverable_wait`) | `03c` turn accumulator (as `scrape_webpage` already does) |
|
||||
| `craft_lens(decision, binding)` | `03` schema-design agent | inline (does the sample-fetch + proposes) | sample crawl billed |
|
||||
| `lock_lens(draft)` / `update_lens` | `03` Lens persistence | inline | — |
|
||||
| `refresh_lens(lens_id)` | `03` `refresh(lens)` | job → `deliverable_wait` | per capability call |
|
||||
| `query_timeline(lens_id, …)` | `04` read API | inline | — |
|
||||
| `list_lenses()` | `04`/`03` read | inline | — |
|
||||
| `craft_tracker(decision, binding)` | `03` schema-design agent | inline (does the sample-fetch + proposes) | sample crawl billed |
|
||||
| `lock_tracker(draft)` / `update_tracker` | `03` Tracker persistence | inline | — |
|
||||
| `refresh_tracker(tracker_id)` | `03` `refresh(tracker)` | job → `deliverable_wait` | per capability call |
|
||||
| `query_timeline(tracker_id, …)` | `04` read API | inline | — |
|
||||
| `list_trackers()` | `04`/`03` read | inline | — |
|
||||
|
||||
- **Capability verbs are a shared tool module** (generated from the Domain ① registry) — `research`
|
||||
can load the same ones; the `analyst` additionally loads the Lens/Timeline tools + the CI prompt.
|
||||
can load the same ones; the `intelligence_agent` additionally loads the Tracker/Timeline tools + the CI prompt.
|
||||
(`scrape_webpage` is the seed; generalize it into the registry-backed set.)
|
||||
- **Slow verbs** (`maps.search`, multi-URL `web.scrape`, `refresh_lens`) dispatch a job and use the
|
||||
- **Slow verbs** (`maps.search`, multi-URL `web.scrape`, `refresh_tracker`) dispatch a job and use the
|
||||
existing `deliverable_wait` poll-until-terminal + live-card path (`02-access.md`).
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Orchestration ≠ Intelligence.** The `analyst` *drives* `03`/`04` via tools; the hot loop,
|
||||
- **Orchestration ≠ Intelligence.** The `intelligence_agent` *drives* `03`/`04` via tools; the hot loop,
|
||||
materiality, and Timeline writes live in `03`/`04`, callable headless (so REST/MCP and Triggers reach
|
||||
the same logic with no agent in the loop).
|
||||
- **Humans get the agent; machines get raw verbs.** REST/MCP callers (devs/external agents) skip this
|
||||
|
|
@ -73,24 +73,23 @@ It owns the **CI playbook** in `system_prompt.md`:
|
|||
|
||||
## MVP cut vs north star
|
||||
|
||||
- **MVP:** the `analyst` subagent + description/prompt · capability verb tools (registry-backed) ·
|
||||
`craft_lens`/`lock_lens`/`refresh_lens`/`query_timeline`/`list_lenses` · intent routing in-prompt.
|
||||
- **North star (deferred):** richer multi-step CI playbooks (auto competitor discovery → multi-Lens
|
||||
setup), proactive "you should watch this" suggestions, cross-Lens synthesis.
|
||||
- **MVP:** the `intelligence_agent` subagent + description/prompt · capability verb tools (registry-backed) ·
|
||||
`craft_tracker`/`lock_tracker`/`refresh_tracker`/`query_timeline`/`list_trackers` · intent routing in-prompt.
|
||||
- **North star (deferred):** richer multi-step CI playbooks (auto competitor discovery → multi-Tracker
|
||||
setup), proactive "you should watch this" suggestions, cross-Tracker synthesis.
|
||||
|
||||
## Locked decisions
|
||||
|
||||
1. CI orchestration is a **net-new builtin subagent** (`analyst`, working name) on the existing
|
||||
1. CI orchestration is a **net-new builtin subagent** (`intelligence_agent`) on the existing
|
||||
runtime — not a runtime rebuild.
|
||||
2. Tools follow the `scrape_webpage` shape: capability executor + access door + `03c` billing.
|
||||
3. Capability verbs are a **shared, registry-generated** tool module; the `analyst` adds Lens/Timeline
|
||||
3. Capability verbs are a **shared, registry-generated** tool module; the `intelligence_agent` adds Tracker/Timeline
|
||||
tools + the CI prompt.
|
||||
4. Intent routing (A vs B) lives **in the subagent prompt**; the headless logic stays in `03`/`04`.
|
||||
5. Slow verbs reuse `deliverable_wait`; nothing new for chat-async.
|
||||
|
||||
## Open questions (carry forward)
|
||||
|
||||
- Subagent **name/persona** (`analyst`? `intelligence`? `scout`?).
|
||||
- Does CI one-shot scraping stay in `research`, or does the `analyst` own all CI-flavored calls (lean:
|
||||
shared verb tools, `analyst` owns the *CI playbook*).
|
||||
- How `craft_lens`'s "review & lock" renders pre-frontend (pure-chat confirmation — ties to `03`'s open Q).
|
||||
- Does CI one-shot scraping stay in `research`, or does the `intelligence_agent` own all CI-flavored calls (lean:
|
||||
shared verb tools, `intelligence_agent` owns the *CI playbook*).
|
||||
- How `craft_tracker`'s "review & lock" renders pre-frontend (pure-chat confirmation — ties to `03`'s open Q).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue