What it does
- Accelerates research and first drafts
- Keeps source and candidate constraints visible
- Produces structured output for fast review
AI Systems & Agents
BlogAgent
An AI editorial workflow that turns a topic into a structured, researched, copy-ready blog draft with human review before publication.
BlogAgent combines bounded LLM agents with deterministic contracts for research, candidate validation, drafting, review, and final output control.
Project Snapshot
Project at a glance
Start here for the project type, use case, my role, the working stack, and its current state.
- 01Type
- Internal editorial tool
- 02Role
- Architecture, product, UX, backend, evaluation
- 03Stack
- Python, FastAPI, LLM workflow, deterministic validation, mock/live providers
- 04Status
- Public repo / portfolio case study
- 05Year
- 2026
01 / Problem
Fluent text is not the same as a reliable draft
Most AI blog generators produce fluent text, but they do not prove that sources exist, recommendations are real entities, or the article respects the count promised in its title. In a “5 best X” post, one small failure - an author confused with a product, six items under a five-item headline, or an unsupported citation - turns a useful draft into unreliable content.
BlogAgent addresses that gap by controlling the workflow between research, candidates, drafting, review, and final output, rather than treating writing as a single model response.
02 / Product goal
Copy-ready, not auto-published
The goal was not to create an autopublishing tool. BlogAgent is an internal system for producing copy-ready drafts: text I can move into my blog editor, review, adjust lightly, and publish manually.
What it does not do
- Post or publish
- Schedule or send content
- Remove the need for editorial judgment
The value is speed plus evidence and control, not hands-free automation.
03 / Architecture decision
Workflow first, agents where they add value
The architecture combines deterministic steps with bounded LLM agents. Code controls sequence, limits, contracts, validation, and final decisions. Models support planning, synthesis, drafting, and review, but they do not freely decide what counts as valid.
- 01Topic
- 02Query Contract
- 03Research / Search
- 04Source Quality
- 05Candidate Ledger
- 06CandidatePack
- 07Writer
- 08Reviewer
- 09Revision / Repair
- 10Final Answer Contract
- 11Copy-ready Draft
04 / Core components
Contracts around the writing work
Query Contract
Locks task type, domain, requested count, answer entity type, and safety constraints before drafting.
Candidate Ledger
Extracts possible entities and rejects fragments, bylines, dates, source titles, brand clusters, and malformed candidates.
CandidatePack
Locks the exact recommendation set the writer is allowed to use.
Writer Agent
Drafts the article inside the locked structure and selected tone profile.
Reviewer / Revision Plan
Checks contract compliance, candidate fidelity, and whether a rewrite or targeted repair is required.
Final Answer Contract
Blocks count mismatches, invalid candidates, unsafe outputs, and incoherent workflow states.
05 / Design lesson
PERSON != PRODUCTThe “Paul Altieri” failure
During testing, a watch recommendation article included “Paul Altieri” as one of the recommended watches. He was a person associated with a source, not a watch. The failure exposed the central risk in recommendation workflows: the writer can only be as reliable as the candidate set it receives.
The fix was not another prompt. It was a candidate cleanliness gate, a CandidatePack quality report, reviewer veto power, and a final contract that prevents polished prose from passing when the underlying candidate set is invalid.
06 / Safety and control
Conservative by design
BlogAgent keeps external effects and high-risk claims outside the autonomous workflow.
- 01No external side effects
- 02Mock mode by default
- 03Live providers are opt-in
- 04API keys stay in environment variables
- 05High-risk finance topics degrade to evidence reports
- 06Human review is required before publication
07 / Evaluation
Test the workflow, not a claim of perfect writing
1,100+tests in mock mode
13 / 13workflow evals
5manual QA topics
Manual QA topics
- Affordable luxury watches
- Summer perfumes
- AI tools for students
- How to choose a summer perfume
- Energy stocks safety fallback
The evals validate workflow behavior, contracts, and safety boundaries in mock mode. Live search and model quality remain source-dependent and require human review.
08 / Result
A controlled drafting system
The result is a practical internal AI workflow: not an autonomous writer, but a controlled drafting system that creates structured, source-aware, copy-ready drafts with enough traceability to review them quickly.
- 01Faster first drafts
- 02Better structure
- 03Clearer recommendation constraints
- 04Safer handling of finance and high-risk content
- 05Debug trace for review
- 06Portfolio-ready example of bounded agentic workflow design
09 / Limitations
What remains deliberately unresolved
- Mock-first by default
- Source extraction is heuristic
- Candidate extraction depends on search quality
- One revision plus one polish pass
- No persistence layer
- Human review still required
- Not designed as public SaaS
10 / What I learned
Most writing failures were workflow failures
The main lesson was that most “AI writing quality” failures were actually identity, counting, validation, and handoff problems. Once the system locked candidates, audited sections, gave the reviewer veto power, and treated the final contract as the source of truth, the agent became more reliable without becoming more autonomous.