Writer + critic

A writer drafts, a critic finds specific problems, the writer rewrites to fix them — all three stages shown. The lift from the critique pass is the argument for focused roles over one do-everything prompt.

README Try it Source

Showcase — Writer + critic

Run

bash bootstrap-secrets.sh              # reads ../../../../.env, writes secrets/
docker compose up --build              # default: PROVIDER=openai

Open http://localhost:3000. Gemini: PROVIDER=gemini docker compose up --build.

What's where

backend/ai_openai.py / backend/ai_gemini.py — writer + critic system prompts, composed in Python.
frontend/app/page.tsx — topic box; final, critique, and draft.

Stop

docker compose down

Run locally

Download the project as a ZIP and run it with Docker. Brings up a FastAPI backend + Next.js frontend on localhost:3000.

Download writer-critic.zip

unzip writer-critic.zip
cd writer-critic
bash bootstrap-secrets.sh   # one-time: pulls API keys into ./secrets
docker compose up --build   # default provider: openai
# or:  PROVIDER=gemini docker compose up --build

Type some input, pick a provider, and run the same code shown in Source against the live API. Sign-in required.

Input

Provider

Output

The same modules the Run button hits. The whole project (frontend, Dockerfile, compose) is in the ZIP under README.

`backend/ai_openai.py`

"""Showcase 1 (OpenAI): a writer/critic pipeline.

Three roles, one output: a writer drafts an explanation, a critic finds specific
problems, the writer rewrites to fix them. You see all three stages, so the
improvement from the critique pass is visible — which is the argument for
splitting the work across focused agents instead of one do-everything prompt.
"""
from openai import OpenAI

_client = OpenAI()

_MODEL = "gpt-5.4-nano"

_WRITER = "You are a concise technical writer. Write a short, clear explanation for a beginner."
_CRITIC = ("You are a sharp editor. List 2-3 specific, actionable problems with the draft "
           "(accuracy, clarity, or missing context). If it's already excellent, say so briefly.")


def _agent(system: str, user: str) -> str:
    return _client.responses.create(model=_MODEL, instructions=system, input=[{"role": "user", "content": user}]).output_text


def run(task: str) -> str:
    t = task.strip()
    if not t:
        return "Give a topic to explain (e.g. 'explain what an API is')."
    draft = _agent(_WRITER, t)
    critique = _agent(_CRITIC, f"TASK: {t}\n\nDRAFT:\n{draft}")
    final = _agent(_WRITER, f"TASK: {t}\n\nYour draft was critiqued:\n{critique}\n\nRewrite it, fixing every issue.")
    return f"FINAL:\n{final}\n\n--- critique that shaped it ---\n{critique}\n\n--- first draft ---\n{draft}"

`backend/ai_gemini.py`

"""Showcase 1 (Gemini): a writer/critic pipeline.

Same three-stage draft/critique/revise, on Gemini.
"""
import os

from google import genai
from google.genai import types

_client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

_MODEL = "gemini-3.1-flash-lite"

_WRITER = "You are a concise technical writer. Write a short, clear explanation for a beginner."
_CRITIC = ("You are a sharp editor. List 2-3 specific, actionable problems with the draft "
           "(accuracy, clarity, or missing context). If it's already excellent, say so briefly.")


def _agent(system: str, user: str) -> str:
    r = _client.models.generate_content(
        model=_MODEL,
        contents=[types.Content(role="user", parts=[types.Part(text=user)])],
        config=types.GenerateContentConfig(system_instruction=system),
    )
    return r.text or ""


def run(task: str) -> str:
    t = task.strip()
    if not t:
        return "Give a topic to explain (e.g. 'explain what an API is')."
    draft = _agent(_WRITER, t)
    critique = _agent(_CRITIC, f"TASK: {t}\n\nDRAFT:\n{draft}")
    final = _agent(_WRITER, f"TASK: {t}\n\nYour draft was critiqued:\n{critique}\n\nRewrite it, fixing every issue.")
    return f"FINAL:\n{final}\n\n--- critique that shaped it ---\n{critique}\n\n--- first draft ---\n{draft}"