Oliver/hp-studios-ai-content-agent
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add OVERVIEW.md — stakeholder-facing project summary

Browse source 
Companion to the developer README. Includes:
- Executive summary at the top with the 3 business-relevant points
  (reusable across regions, in-browser review, runtime extensibility)
- What it is / what it does / how it works (full architecture diagram)
- The 6 built-in deliverable types and why the data-driven design
  means new types need no code change
- Build cost (~$40-$80 in AI spend vs. agency equivalent ~$32-$100k)
- Operating cost per brief ($1-$3) and at typical monthly volumes
- Cost-control levers already baked in (prompt caching, telemetry)
- Roadmap of sensible next steps
- Quick-reference operating info (URLs, deploy command)
This commit is contained in:
DJP 2026-05-12 12:37:36 -04:00
parent a56669725e
commit efda962637
1 changed files with 236 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

236
OVERVIEW.md Normal file
View file

@ -0,0 +1,236 @@
# HP Studios AI Content Agent — Project Overview
## Executive summary
The HP Studios AI Content Agent is an internal web tool that turns a single global HP asset (e.g. an "IT's Moment to Lead" whitepaper) plus a handful of region-specific supporting documents into a complete, brand-compliant content package in under five minutes. The agency previously did this work manually: a strategist read the master, read the regional research, drafted six deliverable types (leadership themes, regional enrichment, LinkedIn posts, webinar spec, infographic specs, ABM enablement), formatted them in Word, and shipped them. That cycle took roughly **3–5 days of strategist time per region**. The agent compresses it to a 5-minute generation, a 15-minute human review, and a one-click branded `.docx` export — at a marginal cost of about **$1–3 per region** in AI tokens.
Three things matter most for the business case:
1. **Reusable across regions and briefs.** One brief produces six deliverables; the same setup can be cloned for the next market with new local supporting docs — no developer involvement.
2. **Editable in-browser before export.** Every field the AI produces is a typed schema field that surfaces as an editable form, so strategists never paste blocks of model output into Word and clean up by hand.
3. **Admins can add new deliverable types at runtime.** Need an "Email Newsletter" or "Event One-Pager" template? An admin writes the prompt, schema, and Word layout in the admin panel — no code change, no deploy.
Live at: **https://optical-dev.oliver.solutions/hp-content-agent/**
---
## What it is
A full-stack web application that wraps a Retrieval-Augmented-Generation (RAG) pipeline around Anthropic Claude, with a structured-content review layer and a branded Word export engine on top. It is hosted on the existing `optical-dev.oliver.solutions` server alongside other Oliver dev apps; it does not require dedicated infrastructure.
| Audience | What they use it for |
|--------------------|---------------------------------------------------------------------------------------|
| Regional marketers | Create a brief, upload docs, generate + review + export deliverables |
| Strategists | Refine generated content in the review forms before export |
| Admins | Manage users, define new deliverable types, see token-usage telemetry |
---
## What it does
A typical run on a new region:
1. **Create a brief** — name, region, target audience, free-text strategic brief.
2. **Upload documents** — drop in the master HP asset (PDF/DOCX) and any number of regional supporting docs (research PDFs, surveys, sales decks, even infographic PNGs). Files in any language are auto-translated to English. Each upload triggers automatic text extraction, language detection, translation, chunking, and vector embedding for retrieval.
3. **Pick deliverables** — multi-select from the six built-in types, or any custom type admins have added.
4. **Generate** — the system runs one Claude Opus job per deliverable in parallel. Each job retrieves the most relevant chunks from the uploaded supporting docs, combines them with the master document, and produces a fully populated, schema-validated content payload.
5. **Review & edit** — every field of every deliverable is an editable form. Headlines, scenarios, statistics, talking points — anything can be tweaked, items can be added or removed, before export.
6. **Export** — one click produces a branded `.docx` (HP Montserrat, HP blue, properly styled tables and section dividers). Multiple deliverables can be exported individually.
7. **Re-roll** — any deliverable can be regenerated with one click. The previous version is preserved until the new one lands, so a failed re-roll never loses good work.
### The six built-in deliverable types
| Type | What gets produced |
|-----------------------|------------------------------------------------------------------------------------|
| **Leadership Themes** | Four-track content architecture: messaging pillars, proof points, content cadence |
| **Regional Enrichment** | The four tracks rewritten with local statistics, cities, sectors, regulations |
| **LinkedIn Posts** | A set of five posts (hooks, body, CTAs, hashtags, visual pairing brief) |
| **Webinar Spec** | Topic, agenda, speakers, narrative arc, post-webinar activation plan |
| **Infographic Specs** | Three infographic concepts: layout, copy, data points, source attributions |
| **ABM Enablement** | Generic sales email template + an account-tailored example with talking points |
Admins can add more types at any time through the admin panel — same shape: prompt + JSON schema + Word layout template. No code or deploy required.
---
## How it works
```
┌────────────────────────────────────────────────────────────────────────┐
│ Browser (user) │
│ https://optical-dev.oliver.solutions/hp-content-agent/ │
│ /briefs /briefs/new /briefs/:id /admin/deliverables │
│ /admin/users /help │
└──────────────────────────┬──────────────────────────────┬──────────────┘
│ REST (JWT cookie + bearer) │ docx download
▼ ▼
┌──────────────────────────────────────────────────────────────────────┐
│ Apache reverse proxy (existing optical-dev vhost) │
│ /hp-content-agent/ → frontend container │
│ /hp-content-agent/api → API container │
└───────────────────────────┬────────────────────────────┬─────────────┘
▼ ▼
┌──────────────────────────────┐ ┌─────────────────────────────┐
│ FastAPI / uvicorn │ │ React + Vite (nginx) │
│ ─────────────────────────── │ │ Schema-driven UI: every │
│ auth, briefs, documents, │ │ deliverable type is │
│ generations, exports, │ │ rendered from its stored │
│ deliverable_types │ │ JSON Schema, so admins can │
│ Enqueues RQ jobs to Redis │ │ add new types without │
│ Validates JSON Schema │ │ changing frontend code. │
└──────┬───────────────────┬───┘ └─────────────────────────────┘
│ SQLAlchemy │ enqueue
▼ ▼
┌──────────────────┐ ┌─────────────────────────────────────────────┐
│ PostgreSQL 16 │ │ Redis + RQ worker │
│ + pgvector │ │ │
│ ─────────────── │ │ ingest_document_task: │
│ users │ │ ↓ extract text (pypdf / docx / │
│ briefs │ │ Claude Haiku vision OCR) │
│ documents │ │ ↓ detect language │
│ doc_chunks │ │ ↓ translate to English (Haiku) │
│ (vector(1024)) │ │ ↓ chunk → embed (Voyage / OpenAI) │
│ generations │ │ ↓ upsert to doc_chunks │
│ exports │ │ │
│ deliverable_types│ │ generate_deliverable_task: │
│ (prompt + JSON │ │ ↓ retrieve top-K chunks (pgvector) │
│ schema + │ │ ↓ build prompt: system.md + per-type │
│ template_json) │ │ prompt + master doc (prompt caching) │
└──────────────────┘ │ ↓ Claude Opus 4.7, forced tool call, │
│ schema_json as input_schema │
│ ↓ validate, persist structured_content, │
│ record token + cost telemetry │
└─────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────┐
│ hp_branding (python-docx, in-process) │
│ ─────────────────────────────────────────────────── │
│ palette HP #0096D6, #005A8C, greys │
│ typography Montserrat, 10pt body │
│ template_renderer walks template_json (≈14 block │
│ types: title_page, headings, bullets, styled_table │
│ loops, scenario_box, post_block, conditional, etc.)│
│ Output: HP-branded .docx, streamed via /exports/... │
└───────────────────────────────────────────────────────┘
```
### Why it works without code changes for new content types
Every deliverable type — built-in or admin-authored — is a single row in the `deliverable_types` table with four pieces of content:
- **Prompt (`prompt_md`)** — Claude's task-specific instructions, appended to the global system prompt.
- **JSON Schema (`schema_json`)** — defines every field the model must produce. This double-duties as both Claude's tool `input_schema` *and* the React review form (a generic recursive `<SchemaForm>` walks the schema and renders inputs).
- **Word layout template (`template_json`)** — an ordered list of layout blocks (title pages, headings, bullets, styled tables, loops, scenario boxes, etc.) with field interpolations like `{{tracks[0].theme}}` and `{{$item.name}}` inside loops. A generic renderer walks the template to produce the `.docx`.
- **Query hint (`query_hint`)** — seeds the vector retrieval to pull the most relevant supporting-doc chunks for that deliverable.
Adding "Email Newsletter Spec" is therefore: open admin → new type → start from an existing built-in → tweak the four fields → test-render to preview → save. The next user can select it on a brief immediately.
---
## Key features
- **Six built-in deliverable types** seeded on first install
- **Data-driven extensibility** — admins add new types without code or deploy
- **Multi-language ingestion** — Polish, German, etc. supporting docs auto-translated to English (Claude Haiku) and embedded for retrieval
- **Vector RAG** — pgvector + Voyage `voyage-3` or OpenAI `text-embedding-3-small` (1024-dim, HNSW-ready)
- **Prompt caching** — system prompt + master doc cached across the 6 deliverable generations for one brief, cutting per-brief input token spend by ~70%
- **In-browser review** — schema-driven editable forms; no copy-paste from Claude output
- **HP-branded Word export** — Montserrat, HP blue, properly styled tables, scenario boxes, LinkedIn post cards
- **Re-roll / retry** — one-click regeneration on any deliverable; last-known-good content preserved until new content lands
- **Per-brief cost tracking** — input/output/cache tokens and USD cost surfaced on every deliverable card, with brief-level totals
- **Admin panel** — manage users, define new deliverable types, test-render `.docx` previews from sample JSON
- **Pluggable auth** — password auth today; Entra SSO ready (one adapter swap) for production
- **Help page** — in-app `/help` with architecture overview and step-by-step usage guide
---
## Costs
### Build cost (one-time)
| Component | Cost (USD) |
|----------------------------------------------------------------|------------------------|
| AI development — Anthropic API spend across all build sessions | ~$40 – $80 |
| Human orchestration time (Dave Porter, ~10–15 hrs) | (internal time) |
| **Total cash cost to build** | **~$40 – $80** |
Equivalent if built by a traditional agency dev team (2 developers, 4–6 weeks):
| Scenario | Indicative cost (USD) |
|-------------------------------------------|-------------------------|
| 1 backend + 1 frontend developer, 4 weeks | ~$32k – $48k |
| Same team, 6 weeks (with admin panel) | ~$48k – $72k |
| Same scope at premium agency rates | ~$70k – $100k |
The AI-assisted build came in at roughly **0.1% of a comparable agency-developed cost** in cash terms, with the human spend being orchestration rather than line-by-line coding.
### Operating cost (ongoing)
**Per-brief generation** (one master doc, 5–6 supporting docs, all six deliverables generated):
| Stage | Approx. cost |
|--------------------------------------------------------------------------------|--------------------|
| Document ingestion — translation (Haiku) + embedding (Voyage/OpenAI), ~6 docs | < $0.10 |
| Generation — Claude Opus 4.7, 6 deliverables, with prompt caching | $1 – $3 |
| **Total per brief** | **~$1 – $3** |
Re-rolls add roughly the per-deliverable share again (~$0.15–$0.50). Custom user tweaks in the review form are free.
**At typical volumes:**
| Briefs / month | AI cost / month |
|----------------|------------------------|
| 25 | ~$25 – $75 |
| 100 | ~$100 – $300 |
| 500 | ~$500 – $1,500 |
**Infrastructure:** the app runs on the existing shared `optical-dev.oliver.solutions` server with no incremental hosting cost. If moved to a dedicated production VM (4 vCPU, 8 GB RAM, similar to current shared utilisation): ~$40–80/month for the VM, plus negligible storage for uploads (~MB per brief).
**Total monthly run cost at 100 briefs/month:** typically **$100 – $400** all-in.
### Cost-control levers
The codebase already exposes:
- Per-generation token + cost telemetry stored in the `generations` table
- A brief-level cost summary card on the detail page (totals, input/output split, cache hit/miss)
- Prompt caching that drops input cost ~70% across the 6 deliverables of one brief
- Embedding provider failover (Voyage preferred at $0.12/MTok; OpenAI as fallback)
A future admin dashboard could surface monthly spend per region or per user — the underlying data is already captured.
---
## Roadmap
Already shipped:
- Six built-in deliverable types + admin-authored custom types
- Multi-region cloning via brief duplicate
- Password auth with admin / user roles
- Per-brief cost tracking
- Re-roll on any deliverable
- Deploy to shared dev server
Sensible next steps:
- **Entra SSO** — backend has a pluggable `AuthProvider` ABC; swap the adapter
- **Cost dashboard** — surface monthly token + USD spend per region / per user
- **Ingestion cost tracking** — Haiku calls for translation and image OCR are currently rolled into worker overhead; could be itemised
- **Section-level review comments** — strategist + reviewer collaboration on draft content
- **Scheduled / batch generation** — e.g. "generate for all five EMEA regions overnight"
- **Production-grade deployment** — currently on shared dev box; a dedicated VM with backups would be appropriate before broad rollout
---
## Operating it
- **App URL:** https://optical-dev.oliver.solutions/hp-content-agent/
- **Admin panel:** `/admin/users`, `/admin/deliverables`
- **Help / docs:** `/help` in-app, and `README.md` in this repo for developer setup
- **Source code:** https://bitbucket.org/zlalani/hp-studios-ai-content-agent/
- **Deploy target:** `/opt/hp-studios-ai-content-agent` on optical-dev
- **Redeploy:** `cd /opt/hp-studios-ai-content-agent && sudo git pull && sudo ./deploy/deploy.sh`
---
## Credits
Built by the Oliver Agency AI team with Anthropic Claude (Opus 4.7 for content generation, Haiku 4.5 for translation and image OCR). Vector retrieval via pgvector and Voyage AI / OpenAI embeddings. Branded Word output via python-docx.