Skip to content

About

Reusable agency operating system for building client operational systems, delivery playbooks, templates, dashboards, and approval-led AI workflows.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

12 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AI Pipeline Systems — Alexander William Neil

I build systems that connect real business data to AI models and deliver the output into working operations. This repo documents the methodology, architecture, and validated results behind that work.

This is not a course project. It is active work for a paying client.


Quick Overview

What I do AI integration and operational pipeline systems for SMBs
Current client Nok Nok Restaurant, Mumbles, Wales (Client 001)
Data processed 46,304 POS rows + 5,000 bookings — cleaned, validated, modelled
Systems live Clean source pipeline, static dashboard pack, review-only model outputs, daily 6am brief
Stack Python · Pandera · DuckDB · n8n · React/Vite · Claude · OpenAI · GitHub · Notion

Current Delivery Milestone

The agency operations layer is now set up around a Notion task packet + workflow tracking system. Client work is tracked as structured task packets with model assignment, context, status, blockers, validation evidence, and approval state. n8n handles the surrounding workflow automation: scheduled checks, freshness digests, exception signals, and internal status updates.

This moves the system from "AI can help build the work" to "AI work can be planned, delegated, tracked, reviewed, and repeated."


What I Do

Most organisations trying to integrate AI have the same problem: they have data, they have access to models, and no reliable system connecting the two. The output is either not trustworthy, not usable, or both.

I build the connecting layer — data ingestion, validation, AI processing, approval gates, and client-facing output — as a system that runs repeatedly, flags its own gaps, and never surfaces a confident answer from incomplete data.

Technical capabilities:

  • AI model integration — connecting structured business data to large language models (Claude, GPT) for analysis, classification, forecasting, and decision support
  • Multi-model orchestration — managing task delegation across models using Notion as a structured task and prompt hub; assigning Codex vs. Claude Code based on task type, context requirements, and cost profile
  • Prompt engineering and output validation — designing prompts that produce structured, testable outputs; validating model behaviour against real data at scale
  • Pipeline architecture — source contracts, schema validation (Pandera), local analytics (DuckDB), workflow automation (n8n)
  • AI testing and confidence scoring — every model output carries a confidence marker; low-confidence outputs are routed to review, not surfaced as reliable
  • Approval gate design — systems where AI prepares and humans approve; governance built in from the start, not added after

Live Work — Nok Nok Restaurant (Client 001)

First complete client engagement. A restaurant in Mumbles, Wales. Used to validate the full pipeline methodology end-to-end on real operational data.

Data cleaned and validated:

  • Square POS — 46,304 transaction rows (UTF-16 encoding, GBP handling, refund logic)
  • ResOS bookings — 5,000 rows (tab-delimited, status normalisation)

Systems built and validated:

System What it does Status
Packet 01 — Ingest & Validate Source contracts, schema validation, import logs, missing source detection Approved with known gaps
Packet 06 — Revenue Forecast Revenue-only forecast baseline from historical POS sales Implemented, review-only
CM Engine — Contribution Margin Item revenue classification while COGS is missing Revenue-only mode
No-Show Engine Scores upcoming bookings for no-show probability; operator recommendation routed to review Gate 2 complete, review-only

Degraded mode in practice: COGS data not yet received from client. Rather than blocking or overclaiming, the system switches to revenue_only_mode=true — outputs are confidence-marked as low, routed to operator review only, and the review pack includes an explicit COGS warning before the sign-off block. The system continues operating usefully on available data without misrepresenting what it knows.

Client interface: static HTML dashboard pack, daily 6am decision brief, current model review pack, approval log, and feedback/outcome capture. React dashboard rebuild is in progress.

Full detail: docs/verticals.md


AI Model Orchestration

A core part of the methodology is how AI models are used together, not just individually.

Context management: Each client project has a CLAUDE.md file — a persistent context document read by Claude Code at the start of every session. It records the project state, active data gaps, decisions made, and current task. No re-explaining the project each session. Claude Code and OpenAI Codex share context through this file and through structured task records in Notion.

Task delegation via Notion: All tasks for a project live in Notion with structured prompts. From there, tasks are delegated to the appropriate model:

  • Complex implementation and multi-step reasoning → Claude Code (with CLAUDE.md context)
  • Spec generation, structured planning, step-by-step task breakdown → OpenAI Codex
  • Routine drafts, summaries, review pack generation → lighter models where appropriate

This means each model handles what it is best suited for, context flows cleanly between sessions and models, and compute cost is managed deliberately rather than by default.

Task packet tracking: The Notion setup now works as an operational control surface for delivery. Each task packet records the brief, prompt, assigned model, context snapshot, current status, blockers, validation evidence, and approval outcome.

Internal agency operations: Claude Cowork (team plan) handles internal workflows — lead triage, briefing drafts, proposal preparation, invoice tracking. Same approval model: Claude prepares, I approve before anything is sent or actioned.


Pipeline Architecture

Every system follows the same approval-led shape:

graph TD
    subgraph Sources["Data Sources"]
        A1["POS System\nSquare"]
        A2["Bookings Platform\nResOS"]
        A3["Supplier Evidence"]
        A4["Kitchen & Supplier\nInput Forms"]
    end

    subgraph Pipeline["Pipeline"]
        B["Ingest & Validate"]
        C["Clean\nDuckDB"]
        D["Map\nHuman approved"]
        E["Aggregate"]
    end

    subgraph Models["Models"]
        F1["Revenue Forecast\nReview-only"]
        F2["CM Engine\nRevenue-only"]
        F3["No-Show Scoring\nReview-only"]
        F4["Demand + Prep\nReview-only"]
    end

    A1 & A2 & A3 & A4 --> B
    B --> C --> D --> E
    E --> F1 & F2 & F3 & F4

    F1 & F2 & F3 & F4 --> G{"Approval Gate\nHuman review required"}

    G --> H["Client Dashboard\nHTML + 6am Brief"]
    G --> I["Approved Action Log"]

    H & I --> J[("Notion\nOperations Backend")]

    style G fill:#6b2d1a,color:#ffffff
    style J fill:#1a3a2e,color:#ffffff
Loading

Each stage is independently testable. Each model output carries a confidence marker. Nothing reaches the client without passing through a human approval gate.

Full breakdown: docs/architecture.md


Current Build

What is live

  • Square POS and ResOS exports have source contracts, clean layers, validation logs, and Packet 01 approval with known gaps recorded.
  • DuckDB-backed scripts exist for revenue forecast, CM Engine, no-show scoring, demand review, and daily summaries; model outputs stay review-only.
  • Static HTML dashboards and review packs exist for source insights, system readiness, refresh status, daily 6am brief, current model review, and owner/operator review.
  • n8n daily rebuild watch and local scheduled refresh logs track expected outputs; automation is status-only.
  • Approval, review outcome, action decision, and recommendation feedback logs exist.

In progress

  • React client dashboard is scaffolded with Vite, React, TypeScript, routes, and seeded typed data; it does not replace the static dashboard pack yet.
  • Supplier mapping, kitchen ontology, and price/COGS evidence are being staged through review-only queues and owner answer capture.
  • JSON/data contracts and AI work-packet workflow are being shaped so dashboard pages can render from reviewed outputs.

Next

  • Generate stable JSON contracts from current pipeline outputs.
  • Rebuild Bookings & Sales and source freshness views as contract-driven React pages.
  • Promote supplier/COGS facts only after owner review; keep purchase and prep actions blocked until then.

Automation

n8n (self-hosted, Docker) — workflow orchestration: scheduled pipeline runs, file detection, exception alerts, internal status digests.

Workflow tracking: Notion task packets track the delivery workflow around each pipeline component: planned, delegated, in progress, blocked, validated, approved, or shipped.

Tiered automation model — automation is implemented incrementally, not all at once:

Tier What it does Status on live work
0–2 Validation, exception detection, AI drafts Active
3–5 Mapping suggestions, approved writes, internal updates Active
6 Business-critical automation (orders, campaigns, external sends) Deferred — trust earned first

This is the approach I'd apply inside any organisation integrating AI: build from the tiers you can validate, earn trust at each level before progressing.

Full methodology: docs/methodology.md


Skills at a Glance

Skill area Specifics
AI model integration Claude (Anthropic API), OpenAI (Codex / GPT); structured output design, model testing
Prompt engineering Structured prompts, context management via CLAUDE.md, multi-model task delegation
Data pipelines Source contracts, Pandera (schema validation), DuckDB (local analytics), Python
Workflow automation n8n (self-hosted Docker), scheduled workflows, file-watch triggers, status digests
AI governance Tiered automation model, confidence scoring, approval gates, degraded mode handling
Version control GitHub, branch-per-task, structured commit history
Client delivery Source contracts, review packs, HTML dashboards, operator approval logs
Context management CLAUDE.md persistent context, Notion task packets, cross-model session continuity

Stack

Layer Tools
AI models Claude (Anthropic), OpenAI Codex / GPT
Language Python
Data ingestion Source contracts and Python loaders
Schema validation Pandera
Local analytics DuckDB
Workflow automation n8n (Docker)
Task and context hub Notion
Version control GitHub
Client interface HTML dashboards
Internal operations Claude Cowork (team plan)

Repo Structure

docs/methodology.md        — Development workflow, multi-model orchestration, V1 checklist
docs/architecture.md       — 8-stage pipeline breakdown, automation tiers, approval model
docs/verticals.md          — Per-vertical notes and full Nok Nok validated results
docs/knowledge-capture.md  — Operational knowledge intake: prep, suppliers, legacy sources
docs/client-system.md      — Client-facing dashboard architecture, approval chain, Notion backend
docs/agency-scaffold.md    — Repeatable scaffold, learning loop, relay system
templates/                 — CLAUDE.md context template and client brief template

Client repos are private. This repo documents the methodology, architecture, and validated results.

About

Reusable agency operating system for building client operational systems, delivery playbooks, templates, dashboards, and approval-led AI workflows.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors