Phase 1: content source of truth — 40 documents across six areas
Satisfies the Phase 1 Definition of Done: - content/ validates cleanly against the frozen schema. `make validate` reports OK: 40 document(s) validated, 0 violations. - Six areas exist, each with an L1 entry: ai-overview, platform-overview, edge-overview, products-overview, history-overview, about-overview. - All six areas have an L2 entry: ai-systems, platform-estate, edge-fleet, products-business, history-engagements, about-narrative. - 28 L3 artefact stubs under content/<area>/l3/. Every artefacts[].url in every document resolves to one of them; the validator proves there are no dangling references (and a deliberately broken copy exits 1). - Every metric value traces to a source line in the evidence notes or the approved metric set in reference/content-map.md (per-metric citations are recorded in the AUD-131 completion comment). - Every document carries confidence and last_verified=2026-10-26; the validator rejects a missing or non-canonical value. - docs/content-redaction.md records the redaction pass: identifiers, third party personal data, credentials and infrastructure detail excluded, with reasons, plus the two numbers that are reported rather than smoothed. Honesty positions held: 3 businesses active (12 adoptions over time), Where-Woof deployed and pre-market, failures kept in (edge-failures), no promotion of in-progress work to delivered. No site code, no templates, no CSS, no rendering (Phase 2).
This commit is contained in:
Documenter
25
content/ai/ai-overview.md
Normal file
25
content/ai/ai-overview.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
id: ai-overview
|
||||
area: ai
|
||||
level: 1
|
||||
title: "AI & Agentic Systems"
|
||||
claim: "Builds and operates sixteen or more AI pipelines — agent harnesses · model routing and cost control · retrieval over a tagged corpus · and a voice front-end that runs a house."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [LangGraph, Prefect, n8n, Qdrant, OmniRoute, Whisper, Piper, MiniMax]
|
||||
metrics: [{label: "pipelines maintained", value: 16}, {label: "model providers behind one gateway", value: 6}, {label: "audio endpoints for spoken output", value: 8}]
|
||||
artefacts: [{type: doc, label: "House AI hub — service topology", url: "content/ai/l3/ai-hub-architecture.md"}, {type: doc, label: "Model routing and cost control", url: "content/ai/l3/ai-omniroute-routing.md"}, {type: doc, label: "Voice pipeline — speech in and speech out", url: "content/ai/l3/ai-voice-pipeline.md"}]
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [ai, agents, routing, retrieval, voice]
|
||||
---
|
||||
|
||||
# AI & Agentic Systems
|
||||
|
||||
**Claim.** Sixteen or more AI pipelines are maintained in production — ten or more on n8n, Prefect and LangGraph, six on Paperclip — with one gateway in front of six model providers, retrieval over a metadata-tagged corpus, and a voice front-end that controls the house.
|
||||
|
||||
**Status.** Running. Every figure on this page traces to the evidence notes; the verification date is 2026-10-26.
|
||||
|
||||
**Why it reads as engineering rather than enthusiasm.** The pipelines run against real obligations — school portals, calendars, email, household audio — and they are operated: routed for cost, guarded before they act, and observed while they run.
|
||||
|
||||
**Start here.** [The capability page](ai-systems.md) explains what is actually run and what the trade-offs were. The three chips above resolve to artefacts below it.
|
||||
70
content/ai/ai-systems.md
Normal file
70
content/ai/ai-systems.md
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
id: ai-systems
|
||||
area: ai
|
||||
level: 2
|
||||
title: "Agent systems that are operated rather than demonstrated"
|
||||
claim: "Maintains sixteen or more production AI pipelines — agent harnesses · prompt-analysis routing across six providers · retrieval filtered by metadata before it searches · and a guarded voice front-end."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [LangGraph, Prefect, n8n, Paperclip, Qdrant, OmniRoute, Whisper, Piper, MiniMax, TUIOS]
|
||||
metrics: [{label: "pipelines maintained", value: 16}, {label: "model providers behind one gateway", value: 6}, {label: "audio endpoints for spoken output", value: 8}, {label: "hosts under standardised agent operations", value: 4}]
|
||||
artefacts: [{type: doc, label: "House AI hub — service topology", url: "content/ai/l3/ai-hub-architecture.md"}, {type: doc, label: "Model routing and cost control", url: "content/ai/l3/ai-omniroute-routing.md"}, {type: doc, label: "Paperclip and n8n pipelines in production", url: "content/ai/l3/ai-paperclip-pipelines.md"}, {type: doc, label: "Retrieval corpus and query graph", url: "content/ai/l3/ai-rag-corpus.md"}, {type: doc, label: "Voice pipeline — speech in and speech out", url: "content/ai/l3/ai-voice-pipeline.md"}, {type: doc, label: "Guardrails — hooks in the model path", url: "content/ai/l3/ai-guardrails.md"}, {type: doc, label: "Memory in two layers", url: "content/ai/l3/ai-memory-layers.md"}]
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [ai, agents, routing, retrieval, voice, guardrails]
|
||||
---
|
||||
|
||||
# Agent systems that are operated rather than demonstrated
|
||||
|
||||
**Capability statement.** This is a working estate, not a prototype: more than sixteen pipelines in production, six providers behind a single gateway, retrieval that filters on metadata before it searches, and a voice front-end used daily by people who did not build it.
|
||||
|
||||
## What is actually run
|
||||
|
||||
**Routing.** Every model call goes through one gateway — OmniRoute. Six providers sit behind it: DeepSeek, MiniMax, OpenRouter, OpenCode-Go, Gemini and OpenAI. Requests are classified before they are sent, so the cheapest model that can do the job gets the job. No project in the estate calls a provider directly; that is a rule, not a preference.
|
||||
|
||||
**Pipelines.** Ten or more are maintained on n8n, Prefect and LangGraph — email scanners, school-portal scanners, calendar scanners, project agents — plus six Paperclip pipelines that run work through a bench of narrow specialist agents behind human approval gates. The estate is registered in a dashboard built to keep track of it.
|
||||
|
||||
**Harnesses.** JEV is a custom harness with its own routing, tool set and memory rather than a wrapper around a vendor SDK. Work is executed as sequences of narrow agents instead of one large prompt; capability is loaded per task through a skill-selection step, so the agent gets what this job needs and not an enormous system prompt.
|
||||
|
||||
**Memory.** Two deliberate layers. Engram keeps what should persist — curated summaries, decisions, prompts and session handoffs in local SQLite, integrated with JEV for fast compaction. Headroom keeps what should not persist out of the window, stripping and compressing prompt context, tool output and logs before they reach the model. Storage and token control are separate problems and are solved separately.
|
||||
|
||||
**Retrieval.** ChromaDB first, then replaced with Qdrant for payload-filtered retrieval and a smaller footprint. LangGraph query graphs on top; Prefect and n8n for ingestion. The corpus is metadata-tagged at ingest, which means retrieval filters before it searches — the difference between a device answer and a work-history answer is a filter, not a better prompt.
|
||||
|
||||
**Voice.** Local Whisper for speech to text with a fallback, Piper for text to speech, MiniMax for a cloned voice with emotion and non-verbal cues. A custom wake word on an ESP32 with LED confirmation. Voice is a system front-end: it controls lighting, music, calendars, shopping, email, SMS and alerts, and it answers through eight Snapcast endpoints with music ducked underneath.
|
||||
|
||||
**Guardrails.** Custom hooks live in the model path and block injection and constrain tool use, built because the house voice channel is shared and unauthenticated and there was no vendor control to borrow. Consequential actions sit behind approval gates, and no model sits in the path of a fast or dangerous command. The public site applies the same reasoning from the other end: the assistant it exposes has no tools at all, so the attack surface is a conversation rather than a shell.
|
||||
|
||||
**Agent operations.** Agent sessions are standardised on TUIOS across four hosts — sessions survive a disconnect, agents report their own state, and approvals land in one inbox. TUIOS is a third-party tool: the contribution is operations and packaging, not authorship. It is pinned at 0.10.1 in a hand-written Nix derivation because nixpkgs lagged at 0.7.0, and its daemon is declared as a systemd user service so the fleet is reproducible rather than hand-installed.
|
||||
|
||||
## Evidence
|
||||
|
||||
| Claim | Evidence | Artefact |
|
||||
|---|---|---|
|
||||
| Sixteen or more pipelines in production | Ten or more on n8n, Prefect and LangGraph plus six on Paperclip | [Paperclip and n8n pipelines](l3/ai-paperclip-pipelines.md) |
|
||||
| Six providers behind one gateway | DeepSeek, MiniMax, OpenRouter, OpenCode-Go, Gemini, OpenAI | [Model routing](l3/ai-omniroute-routing.md) |
|
||||
| Retrieval filters before it searches | Corpus tagged at ingest; Qdrant payload filters; LangGraph query nodes | [Corpus and query graph](l3/ai-rag-corpus.md) |
|
||||
| Spoken output reaches eight endpoints | Eight Snapcast clients with music ducking | [Voice pipeline](l3/ai-voice-pipeline.md) |
|
||||
| Guardrails are code in the path | Injection-blocking hooks and constrained tool use | [Guardrails](l3/ai-guardrails.md) |
|
||||
| Memory is two layers by design | Engram for persistence, Headroom for context control | [Memory layers](l3/ai-memory-layers.md) |
|
||||
| Agent operations are standardised | TUIOS across four hosts with one approval inbox | [House AI hub](l3/ai-hub-architecture.md) |
|
||||
|
||||
## Trade-offs and limits
|
||||
|
||||
- **Local inference was measured, then demoted.** The estate started local on Ollama. Hardware constraints made local inference both slower and more expensive than partitioned remote calls, so heavy flows moved remote while sensitive and low-latency work stayed local. That is a documented comparison, not a taste in hardware.
|
||||
- **The retired stack is in the record.** Airflow DAGs were abandoned for RAM, ChromaDB was replaced by Qdrant, and a visual-builder layer was dropped. Each replacement is stated rather than hidden, because the reasoning is the transferable part.
|
||||
- **Not everything is automated.** Parts of the house are automated end to end and parts still need a person to press the button. The estate is described as it is run, not as it was imagined.
|
||||
- **Cost is bounded by routing, not by hope.** Caps and a refusal path exist so a runaway session cannot become a bill; the routing layer keeps the median request on a cheap model.
|
||||
|
||||
## Drill-downs
|
||||
|
||||
- [House AI hub — service topology](l3/ai-hub-architecture.md) — level 3
|
||||
- [Model routing and cost control](l3/ai-omniroute-routing.md) — level 3
|
||||
- [Paperclip and n8n pipelines in production](l3/ai-paperclip-pipelines.md) — level 3
|
||||
- [Retrieval corpus and query graph](l3/ai-rag-corpus.md) — level 3
|
||||
- [Voice pipeline — speech in and speech out](l3/ai-voice-pipeline.md) — level 3
|
||||
- [Guardrails — hooks in the model path](l3/ai-guardrails.md) — level 3
|
||||
- [Memory in two layers](l3/ai-memory-layers.md) — level 3
|
||||
|
||||
## Period and confidence
|
||||
|
||||
`period: 2020–`. The start is anchored on the homelab year in the evidence notes, because the AI estate and the homelab have the same origin. Confidence is `running`: this is the current arrangement, verified 2026-10-26 against the evidence notes.
|
||||
31
content/ai/l3/ai-guardrails.md
Normal file
31
content/ai/l3/ai-guardrails.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: ai-guardrails
|
||||
area: ai
|
||||
level: 3
|
||||
title: "Artefact — Guardrails · hooks in the model path"
|
||||
claim: "Injection blocking and constrained tool use are code in the model path — built because the house voice channel is shared and unauthenticated."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [OmniRoute, Python]
|
||||
metrics: [{label: "tools exposed by the public assistant", value: 0}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [ai, guardrails, security, artefact]
|
||||
---
|
||||
|
||||
# Artefact — Guardrails · hooks in the model path
|
||||
|
||||
**Status: stub.** A redacted injection-test result lands in Phase 6, when the guardrail library is wired into this site's own assistant.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
The hooks that run before a request reaches a provider and before a response reaches an actuator: injection patterns are blocked, tool use is constrained to a declared set, and consequential actions stop at an approval gate. Behind them, one rule that outranks every prompt — no model sits in the path of a fast or dangerous command.
|
||||
|
||||
## What it proves
|
||||
|
||||
Safety enforced by mechanism. A prompt instruction is a suggestion; a hook is a control.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
The test result in Phase 6, using the same library the house runs. The policy that the public assistant has no tools at all is a Phase 5 and 6 decision and is not negotiable at runtime.
|
||||
31
content/ai/l3/ai-hub-architecture.md
Normal file
31
content/ai/l3/ai-hub-architecture.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: ai-hub-architecture
|
||||
area: ai
|
||||
level: 3
|
||||
title: "Artefact — House AI hub service topology"
|
||||
claim: "One hub fronts the AI estate — intake · routing · pipelines · retrieval · voice output · and a single set of network tools namespaced per household member."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [n8n, Prefect, LangGraph, OmniRoute, Qdrant, MQTT, Snapcast]
|
||||
metrics: [{label: "provider gateway entry points", value: 1}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [ai, architecture, artefact]
|
||||
---
|
||||
|
||||
# Artefact — House AI hub service topology
|
||||
|
||||
**Status: stub.** The diagram and the generated topology dump land in Phase 7 (polish). This stub exists so the level 2 page has no dangling reference.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
A one-page diagram of the hub: request intake (voice · chat · scheduled job), the gateway hop, the pipeline runners, the retrieval path, and the output paths (house speakers, phone alerts, dashboards). Every box is a service that runs; nothing on the diagram is aspirational.
|
||||
|
||||
## What it proves
|
||||
|
||||
That the estate is a designed system with a single gateway and a single set of namespaced tools — not a collection of scripts that happen to share a machine.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
Phase 7. The source facts are in the evidence notes (sections 2 and 4). Capture must be from the live estate, so no diagram is drawn from memory in Phase 1.
|
||||
31
content/ai/l3/ai-memory-layers.md
Normal file
31
content/ai/l3/ai-memory-layers.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: ai-memory-layers
|
||||
area: ai
|
||||
level: 3
|
||||
title: "Artefact — Memory in two layers · Engram and Headroom"
|
||||
claim: "Memory is split by purpose — Engram stores what should persist and Headroom keeps what should not persist out of the context window."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [Engram, Headroom, SQLite, JEV]
|
||||
metrics: [{label: "memory layers", value: 2}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [ai, memory, context, artefact]
|
||||
---
|
||||
|
||||
# Artefact — Memory in two layers · Engram and Headroom
|
||||
|
||||
**Status: stub.** A redacted session handoff and a before-and-after context measurement land in Phase 7.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
Engram is local-first storage for curated summaries, decisions, prompts and session handoffs in SQLite, so a conversation can be resumed in any project; it is integrated with JEV for fast compaction. Headroom is token control: it strips, cleanses and analyses code and logs before they reach the model, compressing rather than truncating.
|
||||
|
||||
## What it proves
|
||||
|
||||
Two distinct problems recognised as two — persistence and window economy — instead of one tool asked to do both.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
Phase 7. Both tools are part of Sam's own workflow; they are deliberately not part of the public assistant, which is stateless by decision (see `reference/decisions.md` D11).
|
||||
31
content/ai/l3/ai-omniroute-routing.md
Normal file
31
content/ai/l3/ai-omniroute-routing.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: ai-omniroute-routing
|
||||
area: ai
|
||||
level: 3
|
||||
title: "Artefact — Model routing and cost control"
|
||||
claim: "Every model call is classified first and sent to the cheapest capable provider — six providers behind one gateway with no direct SDK calls anywhere in the estate."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [OmniRoute, JEV, DeepSeek, MiniMax, OpenRouter, Gemini, OpenAI]
|
||||
metrics: [{label: "providers in rotation", value: 6}, {label: "gateways", value: 1}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [ai, routing, cost, artefact]
|
||||
---
|
||||
|
||||
# Artefact — Model routing and cost control
|
||||
|
||||
**Status: stub.** The routing decision path and a redacted cost table land in Phase 7. No keys or account identifiers are ever published.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
The decision path: request arrives, a prompt-analysis step classifies it, the gateway selects a provider and model, and the response returns with its cost recorded. Plus the comparison that demoted local inference for heavy flows — local Ollama measured slower and more expensive under the available hardware than partitioned remote calls.
|
||||
|
||||
## What it proves
|
||||
|
||||
Cost control implemented as routing and measurement rather than as a monthly promise, and a single chokepoint where provider access can be audited.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
Phase 7. The evidence for the provider list and the local-versus-remote decision is in the evidence notes, section 2 and section 4.
|
||||
31
content/ai/l3/ai-paperclip-pipelines.md
Normal file
31
content/ai/l3/ai-paperclip-pipelines.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: ai-paperclip-pipelines
|
||||
area: ai
|
||||
level: 3
|
||||
title: "Artefact — Paperclip and n8n pipelines in production"
|
||||
claim: "Sixteen or more pipelines run real work — scanners · schedulers · project agents — with specialist agents dispatched by task and human approval gates on anything consequential."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [Paperclip, n8n, Prefect, LangGraph]
|
||||
metrics: [{label: "pipelines on n8n and Prefect and LangGraph", value: 10}, {label: "Paperclip pipelines", value: 6}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [ai, pipelines, agents, artefact]
|
||||
---
|
||||
|
||||
# Artefact — Paperclip and n8n pipelines in production
|
||||
|
||||
**Status: stub.** A redacted run log of one pipeline lands in Phase 7, alongside the pipeline inventory.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
One pipeline shown end to end: trigger, steps, the agent or model each step uses, the approval gate, and the run log with identifiers removed. Alongside it, the inventory of what the sixteen or more pipelines do — email scanners, school-portal scanners, calendar scanners, project oversight, and the household automations.
|
||||
|
||||
## What it proves
|
||||
|
||||
Volume with operations behind it: these are scheduled, logged and monitored, not run once for a demonstration.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
Phase 7. Counts come from the evidence notes, section 3.
|
||||
31
content/ai/l3/ai-rag-corpus.md
Normal file
31
content/ai/l3/ai-rag-corpus.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: ai-rag-corpus
|
||||
area: ai
|
||||
level: 3
|
||||
title: "Artefact — Retrieval corpus and query graph"
|
||||
claim: "Retrieval is filtered by metadata before it searches — a tagged corpus · a four-node LangGraph query graph · and a deliberate replacement of ChromaDB with Qdrant."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [Qdrant, LangGraph, Prefect, n8n, ChromaDB]
|
||||
metrics: [{label: "retrieval stores used over time", value: 2}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [ai, retrieval, rag, artefact]
|
||||
---
|
||||
|
||||
# Artefact — Retrieval corpus and query graph
|
||||
|
||||
**Status: stub.** The query graph diagram and an ingest run log land later; this site's own corpus build is Phase 4.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
The ingest and query path: documents are chunked and tagged with metadata at ingest, stored in Qdrant, and filtered on that metadata before a similarity search runs. The LangGraph graph has four nodes; the fourth decides whether the answer can be given from what was retrieved.
|
||||
|
||||
## What it proves
|
||||
|
||||
Retrieval designed around payload filtering and a hard stop, plus the reasoning for moving off ChromaDB — heavier footprint and weaker filtering — recorded as a decision rather than a migration.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
The query graph diagram in Phase 7. The live demonstration of the same pattern is this site's own retrieval, delivered in Phase 4 and Phase 5.
|
||||
31
content/ai/l3/ai-voice-pipeline.md
Normal file
31
content/ai/l3/ai-voice-pipeline.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: ai-voice-pipeline
|
||||
area: ai
|
||||
level: 3
|
||||
title: "Artefact — Voice pipeline · speech in and speech out"
|
||||
claim: "Speech in on a custom wake word · local transcription · a cloned voice out · and music ducked under every announcement across eight endpoints."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [Whisper, Piper, MiniMax, ESP32, Snapcast, Mopidy, Home Assistant]
|
||||
metrics: [{label: "audio endpoints", value: 8}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [ai, voice, audio, artefact]
|
||||
---
|
||||
|
||||
# Artefact — Voice pipeline · speech in and speech out
|
||||
|
||||
**Status: stub.** A short recording of music ducking under a spoken announcement lands in the optional voice phase. Text describes the chain until then.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
The chain: an ESP32 device with a microphone detects the wake word and confirms with an LED, audio is transcribed locally with Whisper, the request goes through the gateway, and the reply is spoken through Piper or the MiniMax cloned voice over all eight Snapcast endpoints, with music lowered for the announcement and restored afterwards.
|
||||
|
||||
## What it proves
|
||||
|
||||
Voice treated as a system front-end with latency and reliability requirements — not a party trick bolted onto a chatbot.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
Recording in the optional voice phase (Phase 7). The endpoint count and the ducking behaviour are from the evidence notes, sections 1 and 2.
|
||||
Reference in New Issue
Block a user