ac01fffd9a
Architectural snapshot of the lakehouse codebase at the point where the
full matrix-driven agent loop with Mem0 versioning + deletion was
validated end-to-end.
WHAT THIS REPO IS
A clean single-commit snapshot of the lakehouse code. Heavy test data
(.parquet datasets, vector indexes) excluded — see REPLICATION.md for
regen path. Full lakehouse history at git.agentview.dev/profit/lakehouse.
WHAT WAS PROVEN
- Vector retrieval across multi-corpora matrix (chicago_permits + entity
briefs + sec_tickers + distilled procedural + llm_team runs)
- Observer hand-review (cloud + heuristic fallback) gating each candidate
- Local-model agent loop (qwen3.5:latest) with tool use + scratchpad
- Playbook seal on success → next-iter retrieval surfaces it as preamble
- Mem0 versioning + deletion in pathway_memory:
* UPSERT: ADD on new workflow, UPDATE bumps replay_count on identical
* REVISE: chains versions, parent.superseded_at + superseded_by stamped
* RETIRE: marks specific trace retired with reason, excluded from retrieval
* HISTORY: walks chain root→tip, cycle-safe
KEY DIRECTORIES
- crates/vectord/src/pathway_memory.rs — Mem0 ops live here
- crates/vectord/src/playbook_memory.rs — original Mem0 reference
- tests/agent_test/ — local-model agent harness + PRD + session archives
- scripts/dump_raw_corpus.sh — MinIO bucket dump (raw test corpus)
- scripts/vectorize_raw_corpus.ts — corpus → vector indexes
- scripts/analyze_chicago_contracts.ts — real inference pipeline
- scripts/seal_agent_playbook.ts — Mem0 upsert from agent traces
Replication: see REPLICATION.md for Debian 13 clean install + cloud-only
adaptation (no local Ollama).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
94 lines
3.5 KiB
Markdown
94 lines
3.5 KiB
Markdown
# ADR-021: Sparse Data Trust Path — start with nothing, earn everything
|
|
|
|
**Status:** Proposed — 2026-04-17
|
|
**Triggered by:** Legacy staffing company pushback: "we don't have that data"
|
|
**Owner:** J
|
|
|
|
---
|
|
|
|
## The Problem
|
|
|
|
We demonstrated a system with rich worker profiles (18 fields,
|
|
behavioral scores, certifications, communication history). The
|
|
staffing company said: "We don't have any of that. We have a name,
|
|
a phone number, and a contract."
|
|
|
|
They're right. Our demo assumed data that doesn't exist in their
|
|
world. Showing AI that only works with perfect data is worse than
|
|
useless — it builds distrust.
|
|
|
|
## Their Reality
|
|
|
|
Day 1 data for a typical worker:
|
|
- Name
|
|
- Phone number
|
|
- Maybe: city, role, one or two skills mentioned on a call
|
|
|
|
Day 1 data for a contract:
|
|
- Client name
|
|
- Role needed
|
|
- Headcount
|
|
- Start date
|
|
- Maybe: required certs, location
|
|
|
|
That's it. No reliability scores. No availability metrics. No
|
|
communication history. No certifications in a database. The staffing
|
|
coordinator carries that knowledge in their HEAD.
|
|
|
|
## The Trust Path
|
|
|
|
### Phase 1: Work with what they have (Day 1)
|
|
- Accept sparse profiles: name + phone + role. That's enough.
|
|
- Match contracts to workers by role + location only. No scores.
|
|
- The system is useful immediately: "here are the 12 people you
|
|
have tagged as Forklift Operators in IL." That's already faster
|
|
than scrolling a spreadsheet.
|
|
- Don't show empty fields. Don't show 0% bars. Don't show what's
|
|
missing — show what's THERE.
|
|
|
|
### Phase 2: Earn data through use (Week 1-4)
|
|
- Every placement generates a timesheet → reliability starts building
|
|
- Every call logged → communication history accumulates
|
|
- Every check-in → availability becomes real
|
|
- Every cert verified → certification database grows
|
|
- The staffer doesn't "enter data" — they just do their job, and
|
|
the system learns from it.
|
|
|
|
### Phase 3: AI starts helping (Month 2+)
|
|
- Enough data to actually score workers → show reliability
|
|
- Enough history to predict availability → surface it
|
|
- Enough placements to know client preferences → suggest matches
|
|
- The enrichment happened BECAUSE they used the system, not as a
|
|
prerequisite TO use it.
|
|
|
|
## What This Means for the UI
|
|
|
|
- Worker cards must gracefully degrade. Name only? Show name only.
|
|
Name + role? Show name + role. Full profile? Show everything.
|
|
- Never show empty metrics. No "Reliability: 0%" — that looks like
|
|
the worker is unreliable. Just don't show it until there's data.
|
|
- Lead with what the staffer KNOWS: "you placed this worker at
|
|
Company X last month" — that's information they trust because they
|
|
lived it.
|
|
|
|
## What This Means for the Architecture
|
|
|
|
- The vector index works on whatever text exists. A name + role is
|
|
200 characters. That's enough for an embedding. As more data
|
|
arrives, the embeddings get richer and search gets better.
|
|
- The hybrid search works with sparse SQL filters too. "role =
|
|
'Forklift Operator'" is a valid filter even without reliability.
|
|
- The playbook system captures the staffer's decisions: "you picked
|
|
this worker for this contract" → that IS the training data for
|
|
future AI recommendations.
|
|
|
|
## Implementation
|
|
|
|
1. Sparse profile ingest: accept CSV with as few as 2 columns
|
|
(name, phone). Everything else optional.
|
|
2. Graceful UI degradation: worker cards only show fields that exist
|
|
3. Progressive enrichment: timesheet ingest → auto-calculate
|
|
reliability; check-in ingest → auto-calculate availability
|
|
4. Trust indicators: "based on 3 placements" not "Reliability: 87%"
|
|
— show WHERE the number comes from
|