docs: ADR-0014 — unified Profile model + agent registry
Propose a shared substrate for per-user prefs, contexts, per-key consents, and per-agent state so adding an agent stays a manifest change. Updates CLAUDE.md, README, and architecture docs to reflect the multi-agent pipeline (ADR-0013) and the registry direction. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
230
docs/adr/0014-unified-profile-and-agent-registry.md
Normal file
230
docs/adr/0014-unified-profile-and-agent-registry.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# ADR-0014 — Unified Profile model + agent registry
|
||||
|
||||
**Status:** Proposed
|
||||
**Date:** 2026-05-05
|
||||
**Issues:** #30, #111, #112, #113, #114, #115, #116
|
||||
**Supersedes (data model):** ADR-0013 (the agent set stands; this ADR replaces the implicit assumption that prefs/contexts/consents are hardcoded on `users`).
|
||||
|
||||
## Context
|
||||
|
||||
ADR-0013 introduced the multi-agent pipeline: N pre-compute agents emit
|
||||
prompt snippets, an orchestrator LLM assembles them into a tip. The ADR
|
||||
specified the `agent_outputs` table and the orchestrator contract, but
|
||||
left several questions open:
|
||||
|
||||
1. **Where do user preferences live?** `users.consentGiven` is a single
|
||||
boolean. There is no place for quiet hours, tone, allowed tip kinds,
|
||||
or per-integration consent. Each new preference would mean another
|
||||
typed column on `users` — and worse, every new agent needs its own
|
||||
tunable parameters (focus areas, momentum baseline, lateness tolerance)
|
||||
that are clearly per-agent state, not global user state.
|
||||
2. **How are agents discovered?** The orchestrator currently iterates a
|
||||
hardcoded list. Adding an agent means touching the recommender, the
|
||||
admin UI, and the prefs schema in three places.
|
||||
3. **How does context (work / home / vacation) interact with agents?**
|
||||
Some agents should be silenced in some contexts. There is no model.
|
||||
4. **How is per-user agent configuration learned?** Issues #112–#116
|
||||
each want to auto-infer parameters (quiet hours, focus areas, etc.)
|
||||
from history. Without a shared substrate they each reinvent storage,
|
||||
recompute cadence, and cold-start fallback.
|
||||
|
||||
The current ADR-0013 design works for five agents. It will not work for
|
||||
twenty without becoming a tangle.
|
||||
|
||||
## Decision
|
||||
|
||||
Three changes, designed to compose:
|
||||
|
||||
### 1. Agents are plugins with declared schemas
|
||||
|
||||
Every agent ships a manifest (Python, lives next to its code in
|
||||
`ml/agents/<id>/manifest.py`):
|
||||
|
||||
```python
|
||||
class AgentManifest:
|
||||
id: str # 'time-of-day'
|
||||
version: str # bump invalidates cached outputs + inferences
|
||||
pref_schema: dict # JSON Schema for user-tunable knobs
|
||||
context_schema: list[str] # signals it reads, e.g. ['todoist.tasks']
|
||||
required_consents: list[str] # ['data:todoist', 'agent:time-of-day']
|
||||
output_contract: dict # snippet shape (free text + optional tags)
|
||||
ttl_sec: int # snippet freshness for agent_outputs
|
||||
inferred_params: list[InferredParam] # see §3
|
||||
```
|
||||
|
||||
The manifest is the **single point of registration**. The orchestrator,
|
||||
admin UI, and inference framework all read from it. Adding an agent is
|
||||
adding one directory in `ml/agents/` — no edits elsewhere.
|
||||
|
||||
A `GET /api/agents/registry` endpoint (TS recommender → Python proxy)
|
||||
exposes manifests so the admin app can auto-render configuration UI from
|
||||
each `pref_schema`.
|
||||
|
||||
### 2. Unified Profile data model
|
||||
|
||||
Three new tables replace the implicit "fields-on-users" pattern.
|
||||
`users.consentGiven` collapses into `user_consents` (one row,
|
||||
`consent_key='data:core'`); existing data migrates in a single
|
||||
backfill.
|
||||
|
||||
```sql
|
||||
-- Hybrid: typed columns where stable, KV where open-ended.
|
||||
-- Stable globals stay on users (added in this ADR):
|
||||
ALTER TABLE users ADD COLUMN tone TEXT; -- 'direct'|'gentle'|'motivational'
|
||||
ALTER TABLE users ADD COLUMN tip_kinds_json TEXT; -- JSON: allowed tip kinds
|
||||
|
||||
-- Open-ended per-agent prefs land here:
|
||||
CREATE TABLE user_preferences (
|
||||
user_id TEXT NOT NULL REFERENCES users(id),
|
||||
scope TEXT NOT NULL, -- 'orchestrator' | 'agent:<id>'
|
||||
key TEXT NOT NULL, -- e.g. 'quietStart', 'focusAreas'
|
||||
value_json TEXT NOT NULL, -- agent validates against its pref_schema on read
|
||||
updated_at TEXT NOT NULL,
|
||||
source TEXT NOT NULL DEFAULT 'user', -- 'user' | 'inferred'
|
||||
PRIMARY KEY (user_id, scope, key)
|
||||
);
|
||||
|
||||
CREATE TABLE user_consents (
|
||||
user_id TEXT NOT NULL REFERENCES users(id),
|
||||
consent_key TEXT NOT NULL, -- 'data:todoist' | 'data:calendar' | 'agent:focus-area'
|
||||
granted_at TEXT NOT NULL,
|
||||
revoked_at TEXT, -- null = currently active
|
||||
PRIMARY KEY (user_id, consent_key)
|
||||
);
|
||||
|
||||
CREATE TABLE user_contexts (
|
||||
user_id TEXT NOT NULL REFERENCES users(id),
|
||||
name TEXT NOT NULL, -- 'work' | 'home' | 'vacation' | user-named
|
||||
active INTEGER NOT NULL DEFAULT 0, -- boolean
|
||||
schedule_json TEXT, -- optional: when this context is active
|
||||
created_at TEXT NOT NULL,
|
||||
PRIMARY KEY (user_id, name)
|
||||
);
|
||||
```
|
||||
|
||||
Why hybrid (typed for stable globals, KV for per-agent):
|
||||
|
||||
- `tone` and allowed tip kinds are referenced by every recommendation —
|
||||
putting them in JSON imposes a parse on every read.
|
||||
- Per-agent prefs are open-ended (each agent declares its own keys) and
|
||||
validated on read against the agent's `pref_schema`, so KV is correct.
|
||||
|
||||
`user_preferences.source = 'user' | 'inferred'` keeps explicit user
|
||||
overrides distinguishable from inferred values (the inference framework
|
||||
never overwrites a `source='user'` row).
|
||||
|
||||
`user_contexts` ships in this ADR with **manual toggle only**.
|
||||
Auto-inference per agent type is tracked in #112–#116; cross-agent
|
||||
calendar/geo inference is out of scope.
|
||||
|
||||
### 3. Shared context-inference framework
|
||||
|
||||
Each `InferredParam` in a manifest declares:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class InferredParam:
|
||||
key: str # 'quietStart'
|
||||
ttl_sec: int # how often to recompute
|
||||
cold_start_default: Any # value used until enough history exists
|
||||
min_history: int # event count threshold
|
||||
infer: Callable[[UserHistory], Any] # pure function
|
||||
```
|
||||
|
||||
The framework (`ml/agents/inference/`) owns:
|
||||
|
||||
- Scheduling (recomputes per-param via the existing pre-compute scheduler).
|
||||
- Reading history from `tip_views` / `tip_feedback` / `agent_outputs`.
|
||||
- Writing results to `user_preferences` with `source='inferred'`.
|
||||
- Cold-start: returns `cold_start_default` until `min_history` is met.
|
||||
- Versioning: bumping `agent.version` invalidates inferred rows for that agent.
|
||||
- Observability: structured log per recompute (window size, output diff, latency).
|
||||
|
||||
Each per-agent issue (#112–#116) implements only its `infer()` functions;
|
||||
everything else is the framework.
|
||||
|
||||
## Read-through API
|
||||
|
||||
Stays small as N grows because every endpoint is registry-driven:
|
||||
|
||||
```
|
||||
GET /api/profile → { user, prefs (grouped by scope), contexts, consents, agents[] }
|
||||
PATCH /api/profile/prefs/:scope → upserts user_preferences rows (source='user')
|
||||
PATCH /api/profile/consents → grant/revoke
|
||||
PATCH /api/profile/contexts → activate/deactivate / create
|
||||
GET /api/agents/registry → manifests; admin UI auto-renders forms from pref_schema
|
||||
```
|
||||
|
||||
`GET /api/profile` is the read-through used by `ml/serving` and the web
|
||||
client; it's the single endpoint each consumer calls instead of reading
|
||||
the DB directly.
|
||||
|
||||
## Orchestrator flow under this ADR
|
||||
|
||||
```
|
||||
1. Load Profile = { user, prefs, active context, consents } via /api/profile.
|
||||
2. From agent registry, filter eligible agents:
|
||||
- required consents granted
|
||||
- not silenced by active context (declared per-agent)
|
||||
- enabled in user_preferences (default: enabled)
|
||||
3. Pull latest non-expired agent_outputs for the eligible set.
|
||||
4. Build orchestrator prompt:
|
||||
- global prefs (tone, allowed tip kinds)
|
||||
- active context name as hint
|
||||
- agent snippets in eligibility order
|
||||
5. LLM → tip.
|
||||
```
|
||||
|
||||
No hardcoded agent list anywhere in the recommender. The orchestrator
|
||||
prompt template (`v4-orchestrator`) iterates whatever it was handed.
|
||||
|
||||
## Migration plan
|
||||
|
||||
One PR per step; each independently deployable.
|
||||
|
||||
1. **Schema** — add the three tables; add `tone` and `tip_kinds_json` to `users`.
|
||||
2. **Backfill** — write `users.consentGiven` rows into `user_consents` as `data:core`. Keep the column for one release, then drop.
|
||||
3. **Manifest plumbing** — `ml/agents/<id>/manifest.py` for the existing five; `GET /api/agents/registry` proxy.
|
||||
4. **Read-through API** — `/api/profile` + sub-endpoints.
|
||||
5. **Orchestrator cutover** — registry-driven eligibility filter.
|
||||
6. **Inference framework** (#111) — land it; migrate `time-of-day` (#112) as the proof.
|
||||
7. **Per-agent inference** — #113–#116 land independently against the framework.
|
||||
8. **Drop `users.consentGiven`** after one release.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Adding an agent = one directory. Admin UI, prefs storage, consent
|
||||
storage, and inference all auto-pick-up.
|
||||
- Per-agent state lives next to the agent code; nothing global to edit.
|
||||
- User-controlled prefs and inferred prefs use the same storage but stay
|
||||
distinguishable (`source` column).
|
||||
- Consent revocation is row-level and time-stamped; aligns with the
|
||||
privacy stance in CLAUDE.md ("privacy is a feature, not a phase").
|
||||
- Sets up cleanly for #27 (Calendar) and #28 (Health) — they register
|
||||
their own consent keys without schema changes.
|
||||
|
||||
### Negative / risks
|
||||
|
||||
- **JSON validation on read** for per-agent prefs is later than column
|
||||
typing. Mitigated by validating in the manifest's load function and
|
||||
failing closed (use cold-start default if invalid).
|
||||
- **Two-table reads** for the orchestrator (registry + profile + outputs)
|
||||
add latency. Cached profile read keeps it sub-ms in practice.
|
||||
- **Migration window** during which `users.consentGiven` and
|
||||
`user_consents` both exist. Reads must consult both for one release;
|
||||
writes go to `user_consents` only.
|
||||
- **Auto-inference can mislead.** A wrong-but-confident inferred quiet
|
||||
window silences the user when they want pings. Mitigation: every
|
||||
inferred param is overrideable in admin/settings (`source='user'`
|
||||
takes precedence), and inferences only kick in past their
|
||||
`min_history` threshold.
|
||||
|
||||
## What this does NOT change
|
||||
|
||||
- ADR-0013's agent set, snippet contract, or `agent_outputs` table.
|
||||
- ADR-0011's `userProfileFeatures` (ML-derived features, not user prefs).
|
||||
- ADR-0008's LiteLLM gateway pattern.
|
||||
- The orchestrator prompt template name (`v4-orchestrator`); the assembly
|
||||
rule changes, the contract does not.
|
||||
@@ -25,12 +25,37 @@ Session auth
|
||||
expires_at
|
||||
revoked_at?
|
||||
|
||||
Profile profile
|
||||
user_id (pk)
|
||||
timezone
|
||||
quiet_hours jsonb: [{start,end,days}]
|
||||
contexts jsonb: [{name,predicate}] introduced in Phase 2
|
||||
consents jsonb: {integration: {read,write,retain_days}}
|
||||
User (extended) profile ADR-0014
|
||||
+ tone 'direct' | 'gentle' | 'motivational'
|
||||
+ tip_kinds_json jsonb: allowed tip kinds (stable globals)
|
||||
|
||||
UserPreference profile ADR-0014
|
||||
user_id, scope, key (pk)
|
||||
scope 'orchestrator' | 'agent:<id>'
|
||||
value_json open-ended; agent validates against its pref_schema on read
|
||||
source 'user' | 'inferred' (inferred never overwrites user)
|
||||
updated_at
|
||||
|
||||
UserConsent profile ADR-0014
|
||||
user_id, consent_key (pk)
|
||||
consent_key 'data:todoist' | 'data:calendar' | 'agent:focus-area' | ...
|
||||
granted_at
|
||||
revoked_at? null = currently active
|
||||
|
||||
UserContext profile ADR-0014
|
||||
user_id, name (pk) 'work' | 'home' | 'vacation' | user-named
|
||||
active manual toggle in M2; auto-inference per agent in #112-#116
|
||||
schedule_json? optional: when this context is active
|
||||
created_at
|
||||
|
||||
AgentOutput recommender ADR-0013
|
||||
id (pk)
|
||||
user_id
|
||||
agent_id e.g. 'overdue-task' (matches a manifest)
|
||||
prompt_text snippet for the orchestrator prompt
|
||||
signals_snapshot jsonb: inputs the agent consumed
|
||||
computed_at, expires_at computed_at + manifest.ttl_sec
|
||||
agent_version bump to invalidate cached outputs on logic changes
|
||||
|
||||
Credential integrations
|
||||
user_id
|
||||
@@ -53,10 +78,10 @@ Event events
|
||||
TipInstance recommender
|
||||
tip_id (ulid)
|
||||
user_id
|
||||
policy_name "random" | "bandit.linucb" | "remote:v3"
|
||||
policy_name "v4-orchestrator" (ADR-0013) | legacy bandit names retained for history
|
||||
policy_version
|
||||
candidate_source "todoist" | "advice.library" | ...
|
||||
context_snapshot jsonb: features seen at decision time
|
||||
candidate_source "todoist" | "advice.library" | "agent-orchestrator" | ...
|
||||
context_snapshot jsonb: features + agent snippets seen at decision time
|
||||
tip jsonb: {kind,title,body,source,deep_link,meta}
|
||||
created_at
|
||||
shown_at? set when the client reports render
|
||||
|
||||
@@ -48,6 +48,8 @@ User reactions (done / snooze / dismiss) are events too. They close the loop as
|
||||
- **Feast** for feature store when we get there; homegrown adapter until then (Phase 1 seam).
|
||||
- **MLflow** for model registry and experiment tracking; deployed at `o.alogins.net/mlflow`.
|
||||
- **Auth.js** embedded behind an OIDC-shaped boundary (ADR-0004). Swap to a standalone OIDC provider when mobile ships.
|
||||
- **Multi-agent recommendation** (ADR-0013) — pre-compute agents emit prompt snippets, an orchestrator LLM produces the tip. Replaced the ε-greedy bandit (ADR-0007/0012) for explainability, cold-start, and decoupling generation from selection.
|
||||
- **Registry-driven agents + unified Profile** (ADR-0014) — agents are plugins with declared manifests; per-user prefs, contexts, and per-key consents live in shared tables; auto-inferred parameters share a common framework. Adding an agent is a manifest change.
|
||||
- **k3s** as the first step beyond docker-compose — no "compose → full k8s" cliff.
|
||||
|
||||
## AI stack
|
||||
@@ -59,30 +61,43 @@ All LLM inference routes through **LiteLLM** (`llm.alogins.net`) backed by **Oll
|
||||
|
||||
**OpenWebUI** (`ai.alogins.net`) is the human-facing interface for prompt iteration and model testing during development.
|
||||
|
||||
## Decision flow for a new tip (Phase 2 target)
|
||||
## Decision flow for a new tip (M2, ADR-0013 + ADR-0014)
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────┐
|
||||
│ Pre-compute (every 15 min, per registered agent) │
|
||||
│ ml/agents/<id> → prompt snippet → agent_outputs │
|
||||
│ TTL per manifest; agent_version invalidates │
|
||||
└────────────────────────────────────────────────┘
|
||||
|
||||
client ─► gateway ─► recommender (TS)
|
||||
│
|
||||
├─► profile: GET /api/profile
|
||||
│ (user, prefs, active context, consents)
|
||||
│
|
||||
├─► registry: GET /api/agents/registry
|
||||
│ (manifests; eligibility filter inputs)
|
||||
│
|
||||
├─► outputs: pull freshest non-expired agent_outputs
|
||||
│ for eligible agents (consents granted,
|
||||
│ not silenced by active context, enabled)
|
||||
│
|
||||
▼
|
||||
ml/serving (Python)
|
||||
│
|
||||
├─► context: ml/features/context.py
|
||||
│ (tasks + reactions + time patterns → prompt)
|
||||
├─► assemble: v4-orchestrator prompt
|
||||
│ = global prefs + active context + snippets
|
||||
│
|
||||
├─► generate: LiteLLM → Ollama
|
||||
│ → N TipCandidates {content, kind, model, prompt_version}
|
||||
├─► generate: LiteLLM → Ollama → one tip
|
||||
│
|
||||
├─► score: bandit policy scores each candidate
|
||||
│
|
||||
├─► shadows: shadow policies log picks without serving
|
||||
│
|
||||
└─► persist: tip_scores {candidate, policy, features, latency}
|
||||
◄─ best TipCandidate
|
||||
└─► persist: tip_scores {tip, contributing agents,
|
||||
prompt_version, llm_model, latency}
|
||||
◄─ tip
|
||||
```
|
||||
|
||||
**Phase 1 (shipped M1):** candidates come from Todoist task list, no LLM. The bandit scores tasks directly.
|
||||
**Evolution:**
|
||||
- **Phase 1 (M1):** candidates from Todoist; ε-greedy bandit scored tasks directly (ADR-0007, ADR-0012). Superseded.
|
||||
- **Phase 2 early (M2):** LLM-generated candidates ranked by bandit. Superseded mid-milestone.
|
||||
- **Phase 2 current (M2):** multi-agent pipeline (ADR-0013), registry-driven and registry-extensible (ADR-0014). No bandit; the orchestrator LLM reasons over named agent snippets.
|
||||
|
||||
**Phase 2 (shipped M2):** LLM candidates are generated in parallel with Todoist fetch. Both pools are merged, scored by the bandit, and the winner served. `tip_scores` tracks `prompt_version`, `llm_model`, and `tip_kind` for every row.
|
||||
|
||||
Feedback: `POST /feedback → events.emit(reaction)` → online bandit update + `prompt_version` tracked for A/B analysis.
|
||||
Feedback: `POST /feedback → events.emit(reaction)`. No online ML reward loop (ADR-0013 §Consequences); reactions are logged in `tip_feedback` for observability and potential future supervised learning.
|
||||
|
||||
@@ -26,7 +26,7 @@ User taps "Delete account" in settings → hard confirm → `User.deleted_at` se
|
||||
|
||||
## Scope boundaries
|
||||
|
||||
Each integration declares the scopes it requests and the features it derives. The `Profile.consents` column is the source of truth; a scope removed from consent short-circuits derived-feature computation at the feature store.
|
||||
Each integration and each agent declares the consent keys it requires (`data:todoist`, `agent:focus-area`, ...) in its manifest. The `user_consents` table is the source of truth (per-key rows, revocation is a `revoked_at` write — never a delete, so audits stay clean). A revoked consent short-circuits derived-feature computation at the feature store and removes the dependent agent from the orchestrator's eligible set on the next tip. See ADR-0014.
|
||||
|
||||
## Audit
|
||||
|
||||
|
||||
Reference in New Issue
Block a user