Generate Title Headline Hooks

What it is

A Python service that generates audience-catching headlines from a story body while enforcing strict factual integrity. It uses a multi-stage pipeline: extracting the story's structural spine, generating archetype-constrained variants, applying a fail-closed integrity gate (deterministic quote checks and LLM fact-checking), and ranking survivors via heuristic and LLM-based scoring.

Features

• Extracts story spine including tension stakes and supported payoff claims
• Generates headlines across six archetypes like curiosity gap and contrarian
• Fail-closed integrity gate drops fabricated quotes and unsupported claims
• Provider-agnostic LLM interface supporting cloud and local models
• Hybrid ranking system combining heuristic rules and LLM judgment

Quickstart

pip install -e ".[dev]"
export ANTHROPIC_API_KEY=sk-...
uvicorn api.app:app --reload
curl -s localhost:8000/headlines -H 'content-type: application/json' -d '{
  "title": "Flood", "body": "The dam held after an intern caught a crack.",
  "style": "editorial"
}' | jq

Architecture

flowchart TD
    Client[HTTP Client]
    API[FastAPI App]
    Pipeline[Headline Pipeline]
    Spine[Spine Extractor]
    Generator[Archetype Generator]
    Gate[Integrity Gate]
    Ranker[Scorer Protocol]
    Store[SQLite Store]
    LLM[LLM Provider]
    Client --> API
    API --> Pipeline
    Pipeline --> Spine
    Spine --> Generator
    Generator --> Gate
    Gate --> Ranker
    Ranker --> Store
    Spine -.-> LLM
    Generator -.-> LLM
    Gate -.-> LLM
    Ranker -.-> LLM

How it's built

Built with FastAPI for the API layer and a modular Python backend. It implements a provider-agnostic LLMClient protocol supporting Anthropic, Alibaba DashScope, Ollama, and MLX. The core logic is split into spine extraction, archetype-based generation, deterministic and LLM-based integrity gating, and a pluggable Scorer protocol for ranking. Data persistence uses SQLite via a simple Store class.

How it runs

sequenceDiagram
    participant Client
    participant API
    participant Pipeline
    participant LLM
    participant Gate
    participant Ranker
    Client->>API POST /headlines
    API->>Pipeline run
    Pipeline->>LLM extract spine
    LLM-->>Pipeline spine data
    Pipeline->>LLM generate variants
    LLM-->>Pipeline raw headlines
    Pipeline->>Gate check integrity
    Gate->>Gate deterministic quote check
    Gate->>LLM fact integrity check
    LLM-->>Gate verification result
    Gate-->>Pipeline verified variants
    Pipeline->>Ranker score variants
    Ranker-->>Pipeline ranked list
    Pipeline-->>API response
    API-->>Client JSON response

How to apply & reuse

Integrate as a microservice for newsrooms or content platforms needing high-integrity headline variations. Use the /headlines endpoint to submit story text and receive ranked, verified headline options. Extend the Scorer protocol to add custom ranking criteria like CTR prediction models.

At a glance