Naluma Content Pipeline

Automated content production pipeline for a tinnitus information website. AI agents research medical literature, draft articles, run quality checks, and publish to WordPress — with human review at the gate.

How It Works

graph LR
    A[Backlog Item] --> B[Brief Generation]
    B --> C[Research]
    C --> D[Writing]
    D --> E[Quality Gates]
    E --> F{Pass?}
    F -->|No| G[Rewrite]
    G --> E
    F -->|Yes| H[Human Review]
    H --> I[Publish to WordPress]

The pipeline turns a content backlog item into a published article through a series of AI agent steps:

1. Brief Generation -- structures the article outline, keywords, and target audience
2. Human Approval -- operator reviews and approves the brief
3. Research -- gathers evidence from PubMed, web search, and an Obsidian vault
4. Writing -- produces a full article draft from the brief and research dossier
5. Quality Gates -- factuality, SEO, and style checks run in parallel (config-driven per content type)
6. Synthesis -- reconciles feedback, triggers rewrites if needed (up to 3 iterations)
7. Image Generation -- creates a featured image via DALL-E 3 (satellite and cornerstone articles)
8. Human Review -- operator approves or requests changes
9. Publish -- pushes approved articles to WordPress as drafts

A separate research news pipeline scans RSS feeds weekly, triages relevance, and produces per-language digest articles (3-5 items each, FIFO batching from a cross-week pool).

Tech Stack

Layer	Technology
Language	Python 3.12, strict typing (mypy)
Orchestration	Prefect 3.x (self-hosted)
LLM	Anthropic Claude (Sonnet for drafting/reasoning, Haiku for classification)
Structured Output	Anthropic structured output mode with Pydantic JSON schemas
Database	Neon Postgres, SQLAlchemy Core (async via asyncpg + pgvector)
Validation	Pydantic v2 (strict mode)
Dashboard	Streamlit (8 pages, role-based access)
Observability	Langfuse (LLM tracing), Sentry (errors), structlog (logging)
Documentation	MkDocs Material (Cloudflare Pages)
Publishing	WordPress REST API + Polylang (EN/DE)
Deployment	Docker, Fly.io
CI/CD	GitHub Actions

Project Structure

src/
  config.py     # Settings, cost limits, quality gate config, model assignments
  telemetry.py  # Idempotent bootstrap: structlog + Sentry + Langfuse
  logging.py    # structlog configuration
  agents/       # AI agents (brief, researcher, writer, factuality, SEO, style, synthesis,
                #   triage, digest, image, readability) + base, schemas, cost tracker
  tools/        # PubMed, Semantic Scholar, ClinicalTrials.gov, web search, vault reader
                #   (pgvector), keyword data, image gen, R2 storage, image colors,
                #   source scanner, URL validator, source enrichment, citation formatter,
                #   sanitizer
  pipeline/     # Prefect flows (article, brief, batch, publish, resume, research news)
                #   + status machine, quality gate dispatch, run tracker, draft validation
  wordpress/    # WordPress client, Gutenberg converter, ACF, taxonomy, Polylang, schema
  db/           # SQLAlchemy tables (14) + pgvector, queries, models, Alembic migrations

dashboard/      # Streamlit operator dashboard (8 pages, role-based auth)

docs/
  site/         # MkDocs Material source (Diataxis structure)

tests/
  unit/         # Isolated tests, no DB
  integration/  # Real DB tests
  e2e/          # Full pipeline tests with mocked agents
  evaluation/   # LLM-as-judge prompt evaluations (not run in CI)