Prompt-Powered Content Assistant

terminalmkdir -p content-assistant/tests
cd content-assistant

Confirm you are in the right place:

terminalpwd

/Users/you/content-assistant

terminalpython3 -m venv .venv
source .venv/bin/activate

terminalpy -m venv .venv
.venv\Scripts\Activate.ps1

(.venv) /Users/you/content-assistant $

terminalpip install "anthropic>=0.40" pytest

Successfully installed anthropic-0.69.0 pytest-8.3.4 ...

Record it so the project is reproducible. This command writes the exact versions into requirements.txt:

terminalpip freeze > requirements.txt

content-assistant/templates.py

templates.py"""Prompt templates + the single source of truth for brand voice."""

BRAND_VOICE = (
    "Voice rules: warm, precise, no hype. Short sentences. UK spelling. "
    "Never use the words 'revolutionary' or 'game-changer', and never use "
    "exclamation marks."
)

# One template per content type. {voice} is filled with BRAND_VOICE,
# the rest come from the caller's brief.
TEMPLATES = {
    "blog_post": (
        "{voice}\n\n"
        "Write a {words}-word blog post about: {topic}\n"
        "Audience: {audience}.\n"
        "Return JSON with keys: title, meta_description (max 160 chars), "
        "body_markdown, social_variants (a list of 3 short posts)."
    ),
    "product_desc": (
        "{voice}\n\n"
        "Write a product description for: {product}\n"
        "Key features: {features}.\n"
        "Return JSON with keys: title, meta_description, body_markdown, "
        "social_variants (a list of 3 short posts)."
    ),
}


def render(kind: str, **fields) -> str:
    """Fill a template. Raises KeyError if the template name is unknown,
    so typos fail loudly instead of silently producing nothing."""
    if kind not in TEMPLATES:
        raise KeyError(f"unknown template: {kind!r}. "
                       f"known: {list(TEMPLATES)}")
    return TEMPLATES[kind].format(voice=BRAND_VOICE, **fields)

content-assistant/content.py

content.py"""The Content data model + brand/publish rules (pure, testable)."""
from dataclasses import dataclass, field


@dataclass
class Content:
    title: str
    meta_description: str
    body_markdown: str
    social_variants: list[str] = field(default_factory=list)
    approved: bool = False            # only a human sets this to True

    def validate_shape(self) -> None:
        """Enforce the structural rules a CMS would need."""
        if not self.title.strip():
            raise ValueError("title is empty")
        if len(self.meta_description) > 160:
            raise ValueError("meta_description exceeds 160 chars")
        if len(self.social_variants) < 1:
            raise ValueError("need at least one social variant")


BANNED_WORDS = ["revolutionary", "game-changer", "!"]


def brand_violations(text: str) -> list[str]:
    """Return the banned tokens present in text (case-insensitive)."""
    low = text.lower()
    return [w for w in BANNED_WORDS if w in low]


def publish(content: Content) -> str:
    """The safety gate. Refuses unless a human approved AND the brand
    check passes. Returns a confirmation string when allowed."""
    if not content.approved:
        raise PermissionError("cannot publish: not human-approved")
    hits = brand_violations(content.body_markdown)
    if hits:
        raise ValueError(f"brand violation(s): {hits}")
    return f"PUBLISHED: {content.title}"

content-assistant/engine.py

engine.py"""Turns a brief into a Content draft. Mock by default; real API optional."""
import json, os
from templates import render
from content import Content

MODEL = "claude-opus-4-8"


def _mock_generate(prompt: str) -> str:
    """A deterministic stand-in for the model. Returns on-brand JSON so
    the whole pipeline runs without an API key. Note: no banned words."""
    return json.dumps({
        "title": "A Calm Guide to the Topic",
        "meta_description": "A short, clear overview written in plain language.",
        "body_markdown": "## Overview\n\nThis is a clear, on-brand draft.\n",
        "social_variants": ["Post one.", "Post two.", "Post three."],
    })


def _real_generate(prompt: str) -> str:
    """Call the real Claude API. Used only when USE_REAL_API=1."""
    import anthropic
    client = anthropic.Anthropic()      # reads ANTHROPIC_API_KEY from env
    msg = client.messages.create(
        model=MODEL, max_tokens=1500,
        messages=[{"role": "user", "content": prompt}],
    )
    return msg.content[0].text


def generate(kind: str, **brief) -> Content:
    """Render the template, get JSON, parse into a Content draft."""
    prompt = render(kind, **brief)
    use_real = os.environ.get("USE_REAL_API") == "1"
    raw = _real_generate(prompt) if use_real else _mock_generate(prompt)
    data = json.loads(raw)
    draft = Content(
        title=data["title"],
        meta_description=data["meta_description"],
        body_markdown=data["body_markdown"],
        social_variants=data["social_variants"],
    )
    draft.validate_shape()      # reject malformed drafts early
    return draft


if __name__ == "__main__":
    # Run this file directly to see a draft printed.
    d = generate("blog_post", topic="async Python",
                 audience="developers", words=600)
    print("TITLE:", d.title)
    print("SOCIAL POSTS:", len(d.social_variants))
    print("APPROVED:", d.approved, "(not live yet)")

terminalpython engine.py

TITLE: A Calm Guide to the Topic
SOCIAL POSTS: 3
APPROVED: False (not live yet)

content-assistant/tests/test_content.py

tests/test_content.py"""Offline tests — no API key needed (engine uses the mock)."""
import pytest
from templates import render
from content import Content, brand_violations, publish
from engine import generate


def test_render_injects_brand_voice():
    prompt = render("blog_post", topic="x", audience="y", words=100)
    assert "UK spelling" in prompt        # the voice made it in


def test_unknown_template_raises():
    with pytest.raises(KeyError):
        render("nope", topic="x")


def test_generate_returns_valid_draft():
    d = generate("blog_post", topic="x", audience="y", words=100)
    assert d.title and len(d.social_variants) == 3
    assert d.approved is False              # never auto-approved


def test_meta_description_length_enforced():
    bad = Content(title="t", meta_description="x" * 200,
                  body_markdown="b", social_variants=["s"])
    with pytest.raises(ValueError):
        bad.validate_shape()


def test_publish_blocked_without_approval():
    d = generate("blog_post", topic="x", audience="y", words=100)
    with pytest.raises(PermissionError):
        publish(d)                          # not approved -> blocked


def test_brand_violation_blocks_publish():
    d = generate("blog_post", topic="x", audience="y", words=100)
    d.body_markdown = "This is revolutionary."   # banned word
    d.approved = True                          # even approved...
    with pytest.raises(ValueError):
        publish(d)                          # ...brand check still blocks

terminalpython -m pytest tests/ -v

tests/test_content.py::test_render_injects_brand_voice PASSED
tests/test_content.py::test_unknown_template_raises PASSED
tests/test_content.py::test_generate_returns_valid_draft PASSED
tests/test_content.py::test_meta_description_length_enforced PASSED
tests/test_content.py::test_publish_blocked_without_approval PASSED
tests/test_content.py::test_brand_violation_blocks_publish PASSED

6 passed in 0.05s

1. Create a key at console.anthropic.com → API Keys. It looks like sk-ant-....

2. Set it and the live-mode flag in your terminal (macOS / Linux):

terminalexport ANTHROPIC_API_KEY="sk-ant-your-key-here"
export USE_REAL_API=1

On Windows (PowerShell):

terminal$env:ANTHROPIC_API_KEY="sk-ant-your-key-here"
$env:USE_REAL_API="1"

3. Run the same file — it now calls Claude:

terminalpython engine.py

TITLE: A Measured Introduction to Async Python
SOCIAL POSTS: 3
APPROVED: False (not live yet)