BacklinkContent Engine - Next-A1 SERP-First Implementation

A SERP-first, intent-first backlink content engine that generates publication-ready backlink articles with full traceability, quality control, and strict adherence to the Next-A1 framework.

Overview

This engine takes three simple inputs:

• Publisher domain (where content will be published)
• Target URL (the page receiving the backlink)
• Anchor text (the link text)

...and produces publication-ready backlink content with:

• Full SERP analysis and intent modeling
• Strategic bridge type recommendation (strong, pivot, wrapper)
• LSI-optimized content with proper anchor placement
• Trust source integration (T1-T4 hierarchy)
• Comprehensive QC validation
• Complete traceability and explainability

Key Features

Next-A1 Framework Implementation

• Variabelgiftermål (Variable Marriage): Aligns publisher, anchor, target, and search intent
• SERP-First Approach: Drives content strategy from dominant SERP intent
• Bridge Types: Intelligent strategy selection (strong, pivot, wrapper)
• Trust Policy: T1→T2→T3→T4 source prioritization
• LSI Quality: 6-10 relevant terms within ±2 sentence window
• Autofix-Once: Single automatic correction attempt with loop protection
• Quality Control: Comprehensive validation against Next-A1 requirements

Modular & Extensible Architecture

All components designed for reusability in other SEO tools:

• PageProfile: Reusable web scraping and profiling
• SERP Analysis: Intent classification and pattern extraction
• Intent Modeling: Publisher-anchor-target-SERP alignment
• QC System: Configurable quality validation

Production-Ready Features

• Deterministic state machine (RECEIVE → PREFLIGHT → WRITE → QC → DELIVER)
• JSON schema validation
• Structured logging with full execution trace
• Mock mode for testing without API costs
• Comprehensive error handling and recovery

Installation

Prerequisites

• Python 3.9+
• Anthropic API key (for Writer Engine)
• Optional: SERP API key (for real SERP data)

Setup

# Clone the repository
git clone <repository-url>
cd BACOWR

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export ANTHROPIC_API_KEY="your-api-key-here"
# Optional:
export SERP_API_KEY="your-serp-api-key"

Configuration

Configuration files in config/:

• thresholds.yaml: QC thresholds (LSI, readability, trust requirements)
• policies.yaml: Autofix policies and industry compliance rules

Schemas in schemas/:

• next-a1-spec.json: Complete Next-A1 specification
• backlink_job_package.schema.json: BacklinkJobPackage JSON schema

Usage

Basic Usage

python main.py \
  --publisher example-publisher.com \
  --target https://client.com/product \
  --anchor "bästa valet för produktkategori"

Advanced Options

python main.py \
  --publisher example-publisher.com \
  --target https://client.com/product \
  --anchor "best choice" \
  --anchor-type partial \
  --min-words 1200 \
  --language sv \
  --serp-mode mock \
  --output ./output/ \
  --log-level DEBUG

Options

Option	Description	Default
--publisher	Publisher domain (required)	-
--target	Target URL (required)	-
--anchor	Anchor text (required)	-
--anchor-type	Anchor type hint: exact, partial, brand, generic	Auto-detect
--min-words	Minimum word count	900
--language	Language override (sv, en, etc.)	Auto-detect
--output	Output directory	./storage/output
--serp-mode	SERP mode: mock or api	mock
--serp-api-key	SERP API key	$SERP_API_KEY
--writer-api-key	Anthropic API key	$ANTHROPIC_API_KEY
--writer-model	Claude model	claude-sonnet-4-5-20250929
--log-level	Logging level	INFO
--json-logs	Output JSON-formatted logs	false

Output

The engine generates comprehensive output for each job:

storage/output/
└── <job-id>_article.md              # The generated article
└── <job-id>_job_package.json        # Complete job package
└── <job-id>_extensions.json         # Next-A1 extensions
└── <job-id>_qc_report.json          # QC validation results
└── <job-id>_execution_log.json      # State machine trace

Output Files

Article (*_article.md):

• Publication-ready backlink content in Markdown
• Structured with H1-H3 headings
• Strategic anchor placement
• LSI-optimized near-window
• Trust source integration

Job Package (*_job_package.json):

• Complete input data and analysis
• Publisher, target, and anchor profiles
• SERP research extension
• Intent extension
• Generation constraints

Extensions (*_extensions.json):

• links_extension: Bridge type, anchor placement, LSI, trust, compliance
• intent_extension: Intent alignment, recommended bridge, required subtopics
• qc_extension: Anchor risk, readability, signals used
• serp_research_extension: SERP analysis data

QC Report (*_qc_report.json):

• Overall status: pass, warning, fail, needs_signoff
• Detailed issues with severity levels
• Autofix recommendations
• Human sign-off triggers

Execution Log (*_execution_log.json):

• Complete state machine trace
• Timestamps for each transition
• Success/failure indicators
• Debugging data

Architecture

Pipeline Flow

RECEIVE → PREFLIGHT → WRITE → QC → DELIVER
           ↓           ↓      ↓
         ABORT      ABORT  RESCUE (AutoFixOnce)

States:

1. RECEIVE: Accept input (publisher, target, anchor)
2. PREFLIGHT: Assemble BacklinkJobPackage
   • Profile target page
   • Profile publisher site
   • Classify anchor
   • Select SERP queries
   • Fetch and analyze SERP data
   • Model intent alignment
3. WRITE: Generate content with Writer Engine
4. QC: Validate against Next-A1 requirements
5. RESCUE: AutoFixOnce attempt (if fixable issues)
6. DELIVER: Output successful result
7. ABORT: Terminate on critical failure

Core Components

Analysis Pipeline (src/modules/):

• page_profile.py: Reusable web scraping and profiling
• target_profiler.py: Target page analysis
• publisher_profiler.py: Publisher site analysis
• anchor_classifier.py: Anchor text classification
• query_selector.py: SERP query generation
• serp_fetcher.py: SERP data fetching (mock/real)
• serp_analyzer.py: SERP intent and pattern analysis
• intent_modeler.py: Intent alignment and bridge strategy

Generation Pipeline (src/pipeline/):

• job_assembler.py: BacklinkJobPackage assembly
• writer_engine.py: LLM-based content generation
• state_machine.py: Pipeline orchestration

Quality Control (src/qc/):

• quality_controller.py: QC validation and AutoFixOnce

Utilities (src/utils/):

• logger.py: Structured logging
• validation.py: JSON schema validation

Next-A1 Framework

Variabelgiftermål (Variable Marriage)

The core principle: Content must marry four dimensions:

1. Publisher (publication site role and voice)
2. Anchor (link text and implied intent)
3. Target (destination page offer)
4. Intent (dominant SERP search intent)

Bridge Types

Strong Bridge:

• Direct, natural connection
• All dimensions aligned
• Publisher niche overlap ≥ 0.7
• Trust requirement: 1 source

Pivot Bridge:

• Thematic bridge strategy
• Partial alignment
• Publisher niche overlap 0.4-0.7
• Trust requirement: 1-2 sources

Wrapper Bridge:

• Meta-frame strategy
• Low alignment (overall=off acceptable)
• Build neutral frame (methodology, risk, comparison)
• Trust requirement: 2-3 sources for triangulation

Trust Policy

Source prioritization (T1 → T2 → T3 → T4):

• T1: Government, official standards
• T2: Academic, peer-reviewed research
• T3: Industry organizations, whitepapers
• T4: Reputable media (fallback only)

Constraints:

• Never link to direct competitors
• Prefer Swedish sources for SE markets
• Use PLATSFÖRSLAG placeholder if source unknown

LSI Requirements

• Count: 6-10 relevant terms
• Window: ±2 sentences around link
• Quality: Entity cluster diversity, not just synonyms
• Sourcing: From target entities + SERP subtopics

Anchor Placement

• Forbidden: Never in H1 or H2
• Preferred: Middle section (H2 section 2-3)
• Paragraph: First or second paragraph in section
• Context: After establishing theme, before CTA

Testing

Run Tests

# Install test dependencies
pip install pytest pytest-cov

# Run all tests
pytest

# Run with coverage
pytest --cov=src tests/

# Run specific test
pytest tests/test_pipeline_smoke.py -v

Mock Mode

For testing without API costs, use --serp-mode mock:

• Generates realistic synthetic SERP data
• No Writer Engine calls (requires API key anyway)
• Full pipeline validation

Extensibility

This engine is designed for reuse across multiple SEO tools:

Reusable Components

PageProfile Module:

• Web scraping and content extraction
• Language detection and entity extraction
• Can power: content audits, competitive analysis, link analysis

SERP Analysis:

• Intent classification
• Pattern extraction
• Page archetype detection
• Can power: keyword research, content gap analysis, rank tracking

Intent Modeling:

• Publisher-target-anchor alignment
• Content strategy recommendation
• Can power: content planning, editorial calendars, topic clustering

QC System:

• Configurable quality validation
• Autofix logic framework
• Can power: content QA tools, style checkers

Integration Points

As a Library:

from src.pipeline.job_assembler import BacklinkJobAssembler
from src.pipeline.writer_engine import WriterEngine

# Assemble job package
assembler = BacklinkJobAssembler(serp_mode="api")
job_package, valid, error = assembler.assemble_job_package(
    publisher_domain="example.com",
    target_url="https://target.com",
    anchor_text="best solution"
)

# Generate content
writer = WriterEngine(api_key="...")
article, extensions, success, error = writer.generate_content(job_package)

As a Service:

• The state machine can be wrapped in a REST API
• Job packages can be queued for async processing
• Results can be stored in a database for analytics

Roadmap

Current Status: MVP/Beta

• ✅ Complete Next-A1 implementation
• ✅ Full pipeline (RECEIVE → DELIVER)
• ✅ QC validation
• ✅ Mock SERP support
• ✅ CLI interface
• ✅ Comprehensive documentation

Next Steps

1. Real SERP Integration: Connect to SerpApi/Serper
2. AutoFix Implementation: Complete autofix logic for all issue types
3. Enhanced LLM Prompts: Refine writer prompts for better output
4. Testing: Expand test coverage
5. Web UI: Build frontend interface with Figma
6. Analytics Dashboard: Track job success rates, QC patterns
7. Database Integration: Store results for historical analysis
8. MCP Integration: Build MCP server for external tool integration

Future Enhancements

• Advanced NER for better entity extraction
• ML-based intent classification
• Semantic clustering for topic modeling
• SERP feature extraction (PAA, featured snippets)
• Historical SERP tracking
• Multi-language optimization
• A/B testing framework for content variants

Troubleshooting

Common Issues

Import Errors:

# Make sure you're in the project root and venv is activated
source venv/bin/activate
pip install -r requirements.txt

API Key Errors:

# Set environment variable
export ANTHROPIC_API_KEY="your-key-here"

# Or pass as argument
python main.py --writer-api-key "your-key-here" ...

SERP Fetch Failures:

• Use --serp-mode mock for testing
• Check SERP API key if using --serp-mode api
• Review logs with --log-level DEBUG

QC Failures:

• Check *_qc_report.json for detailed issues
• Review recommendations for fixes
• Adjust thresholds in config/thresholds.yaml if needed

Contributing

This is a standalone project designed for production use and extensibility.

Guidelines:

• Follow existing code style (Black formatting)
• Add tests for new features
• Update documentation
• Keep modules focused and reusable
• Maintain Next-A1 compliance

License

[To be determined]

Contact

For questions, issues, or collaboration:

• Open an issue on GitHub
• [Contact information]

---

Built with Next-A1 Framework SERP-First. Intent-First. Production-Ready.

BACOWR – BacklinkContent Engine (Next-A1)

Backlink Article Content Orchestration With Refinement

Ett ramverk för automatiserad, SERP-driven länkinnehållsproduktion baserat på Next-A1 specifikationen.

📋 Översikt

BACOWR är en produktionsklar motor för att skapa högkvalitativa backlink-artiklar som:

• ✅ Analyserar SERP för intent och toppresultat
• ✅ Profilerar målsida och publisher automatiskt
• ✅ Genererar backlink-innehåll som naturligt passar SERP-landskapet
• ✅ Validerar kvalitet med inbyggd QC (Quality Control)
• ✅ Exporterar till Google Sheets/Docs för enkel delning och överblick
• ✅ Loggar hela processen för spårbarhet

Tre-input-paradigm

Motorn kräver endast tre inputs:

{
  "publisher_domain": "example-publisher.com",
  "target_url": "https://client.com/product-x",
  "anchor_text": "bästa valet för [tema]"
}

Därifrån sker allt annat automatiskt.

🏗️ Arkitektur

Projektstruktur

BACOWR/
├── config/
│   ├── thresholds.yaml                 # ✅ QC-regler och tröskelvärden
│   └── policies.yaml                   # ✅ AutoFix policies och blocking conditions
├── src/
│   ├── __init__.py
│   ├── api.py                          # ✅ Main API: run_backlink_job() (mock)
│   ├── production_api.py               # ✅ Production API with full LLM integration
│   ├── qc/
│   │   ├── __init__.py
│   │   ├── models.py                   # ✅ QCReport, QCIssue, AutoFixLog
│   │   └── quality_controller.py      # ✅ Komplett QC-system
│   ├── engine/
│   │   ├── __init__.py
│   │   ├── state_machine.py            # ✅ State machine med loop-skydd
│   │   └── execution_logger.py         # ✅ Execution logging
│   ├── profiling/
│   │   ├── __init__.py
│   │   ├── page_profiler.py            # ✅ URL profiling (target & publisher)
│   │   └── llm_enhancer.py             # ✅ LLM-enhanced profiling
│   ├── research/
│   │   ├── __init__.py
│   │   ├── serp_researcher.py          # ✅ Mock SERP researcher
│   │   └── ahrefs_serp.py              # ✅ Ahrefs Enterprise API integration
│   ├── analysis/
│   │   ├── __init__.py
│   │   └── intent_analyzer.py          # ✅ Intent alignment analysis
│   ├── writer/
│   │   ├── __init__.py
│   │   ├── writer_engine.py            # ✅ Mock writer for testing
│   │   └── production_writer.py        # ✅ Multi-LLM production writer
│   └── export/
│       ├── __init__.py
│       ├── README.md                    # ✅ Complete export documentation
│       ├── google_auth.py               # ✅ Google OAuth & Service Account auth
│       ├── google_sheets_exporter.py    # ✅ Export to Google Sheets
│       └── google_docs_exporter.py      # ✅ Export to Google Docs
├── tests/
│   ├── test_schema_validation.py       # ✅ JSON Schema-validering
│   ├── test_live_validation.py         # ✅ Live E2E-validering
│   ├── test_qc_system.py               # ✅ QC-tester (Del 3A)
│   ├── test_e2e_mock.py                # ✅ E2E mock pipeline-tester
│   ├── test_page_profiler.py           # ✅ PageProfiler tests (14/14)
│   ├── test_serp_researcher.py         # ✅ SERP tests (14/14)
│   ├── test_intent_analyzer.py         # ✅ Intent tests (26/26)
│   └── test_writer_engine.py           # ✅ Writer tests (12/12)
├── api/
│   ├── app/
│   │   ├── main.py                      # ✅ FastAPI application
│   │   ├── database.py                  # ✅ SQLAlchemy database setup
│   │   ├── models/                      # ✅ Database models & schemas
│   │   ├── routes/                      # ✅ API endpoints
│   │   │   ├── jobs.py                  # ✅ Job management
│   │   │   ├── backlinks.py             # ✅ Backlink tracking
│   │   │   ├── analytics.py             # ✅ Analytics & metrics
│   │   │   ├── export.py                # ✅ Google Sheets/Docs export
│   │   │   └── ...
│   │   └── services/                    # ✅ Business logic services
│   └── README.md                        # ✅ API documentation
├── examples/
│   ├── example_job_package.json        # ✅ Referens-implementation
│   ├── batch_jobs_example.csv          # ✅ Example batch CSV
│   ├── batch_jobs_example.json         # ✅ Example batch JSON
│   └── export_integration_example.py   # ✅ Google export integration demo
├── storage/
│   ├── output/                         # ✅ Single job outputs
│   ├── batch_output/                   # ✅ Batch processing outputs
│   └── batch_chunks/                   # ✅ Scheduled batch chunks
├── backlink_job_package.schema.json    # ✅ JSON Schema (single source of truth)
├── BacklinkJobPackage.json             # ✅ Original exempel-jobb
├── backlink_engine_ideal_flow.md       # ✅ Idealflöde dokumentation
├── next-a1-spec.json                   # ✅ Next-A1 specifikation
├── NEXT-A1-ENGINE-ADDENDUM.md          # ✅ Del 2 tillägg och krav
├── PRODUCTION_GUIDE.md                 # ✅ Complete production guide
├── BATCH_GUIDE.md                      # ✅ Complete batch processing guide
├── main.py                             # ✅ CLI entrypoint (mock)
├── production_main.py                  # ✅ Production CLI with LLM
├── batch_runner.py                     # ✅ Batch processing CLI
├── batch_monitor.py                    # ✅ Batch monitoring dashboard
├── batch_scheduler.py                  # ✅ Batch scheduling utility
├── cost_calculator.py                  # ✅ Cost estimation tool
├── quickstart.py                       # ✅ Interactive quick start guide
├── .env.example                        # ✅ Configuration template
├── requirements.txt                    # ✅ Python dependencies
└── README.md                           # Denna fil

Output-filer

När motorn körs i mock-mode (redo nu) produceras:

1. {job_id}_job_package.json – Komplett BacklinkJobPackage
2. {job_id}_article.md – Genererad backlink-artikel (≥900 ord)
3. {job_id}_qc_report.json – QC-rapport med issues och AutoFix-logs
4. {job_id}_execution_log.json – State machine-spårning

Alla filer sparas i storage/output/ (konfigurerbart).

📦 Installation

Krav

• Python 3.9+
• pip

Quick Setup (Recommended)

# 1. Klona repot
git clone https://github.com/robwestz/BACOWR.git
cd BACOWR

# 2. Skapa virtuell miljö
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 3. Installera beroenden
pip install -r requirements.txt

# 4. Kopiera och redigera .env
cp .env.example .env
# Lägg till dina API-nycklar i .env (valfritt för dev-läge)

# 5. Kör BACOWR
python run_bacowr.py --mode dev \
  --publisher example.com \
  --target https://example.com/page \
  --anchor "test link"

Alternative: Use Startup Scripts

# Unix/Linux/macOS
./start_bacowr.sh

# Windows
.\start_bacowr.ps1

These scripts automatically set up the virtual environment and install dependencies.

🚀 Quick Start

Method 1: Unified Entry Point (Recommended)

The new run_bacowr.py provides a single, simple entry point for all modes:

# Development mode (uses mock data, no API keys needed)
python run_bacowr.py --mode dev \
  --publisher example.com \
  --target https://example.com/page \
  --anchor "example link"

# Production mode (requires LLM API key)
export ANTHROPIC_API_KEY='your-key-here'
python run_bacowr.py --mode prod \
  --publisher aftonbladet.se \
  --target https://sv.wikipedia.org/wiki/Artificiell_intelligens \
  --anchor "läs mer om AI"

# Interactive demo
python run_bacowr.py --mode demo

Method 2: Startup Scripts

# Unix/Linux/macOS
./start_bacowr.sh              # Runs in dev mode
./start_bacowr.sh --mode prod  # Runs in production mode

# Windows
.\start_bacowr.ps1              # Runs in dev mode
.\start_bacowr.ps1 -Mode prod   # Runs in production mode

Method 3: Interactive Quick Start

# Set API key
export ANTHROPIC_API_KEY='your-key-here'

# Run interactive guide
python run_bacowr.py --mode demo --demo-type quickstart

This will guide you through generating your first article step-by-step.

Single Article Generation

Generate a single article in production mode:

# Using run_bacowr.py (recommended)
python run_bacowr.py --mode prod \
  --publisher aftonbladet.se \
  --target https://sv.wikipedia.org/wiki/Artificiell_intelligens \
  --anchor "läs mer om AI" \
  --llm anthropic \
  --strategy multi_stage

# Or using legacy script (still supported)
python production_main.py \
  --publisher aftonbladet.se \
  --target https://sv.wikipedia.org/wiki/Artificiell_intelligens \
  --anchor "läs mer om AI" \
  --llm anthropic \
  --strategy multi_stage

Output:

• Article generated in ~30-60 seconds
• QC report with quality validation
• Full job package with profiling data
• Execution log for debugging

Batch Processing - Multiple Articles

Process multiple articles efficiently:

# Create batch input file (jobs.csv)
cat > jobs.csv << EOF
publisher,target,anchor,strategy
aftonbladet.se,https://example.com/page1,anchor 1,multi_stage
svd.se,https://example.com/page2,anchor 2,single_shot
EOF

# Run batch (sequential)
python batch_runner.py --input jobs.csv

# Run batch with parallel processing
python batch_runner.py --input jobs.csv --parallel 3 --rate-limit 10

# Monitor progress
python batch_monitor.py --watch storage/batch_output/

See BATCH_GUIDE.md for comprehensive batch processing documentation.

Cost Estimation

Estimate costs before running:

# Estimate single job
python cost_calculator.py --jobs 1 --provider anthropic --strategy multi_stage

# Estimate batch file
python cost_calculator.py --input jobs.csv --details

🐳 Docker Usage

Run with Docker Compose

# Copy .env.example to .env and add your API keys
cp .env.example .env
# Edit .env with your actual API keys

# Start services
docker-compose up --build

# The API will be available at http://localhost:8000
# API documentation at http://localhost:8000/docs

Run Standalone Docker Container

# Build image
docker build -t bacowr .

# Run in production mode
docker run --env-file .env bacowr \
  python run_bacowr.py --mode prod \
  --publisher example.com \
  --target https://example.com \
  --anchor "test link"

# Run API server
docker run -p 8000:8000 --env-file .env bacowr \
  python -m uvicorn api.app.main:app --host 0.0.0.0 --port 8000

🛠️ Advanced Usage

CLI (Mock Mode)

Kör full pipeline i mock-mode (ingen extern API krävs):

# New unified entry point
python run_bacowr.py --mode dev \
  --publisher example-publisher.com \
  --target https://client.com/product-x \
  --anchor "bästa valet för [tema]"

# Or using legacy script
python main.py \
  --publisher example-publisher.com \
  --target https://client.com/product-x \
  --anchor "bästa valet för [tema]" \
  --mock

Output:

======================================================================
BACOWR - BacklinkContent Engine (Next-A1)
======================================================================

Publisher:  example-publisher.com
Target:     https://client.com/product-x
Anchor:     bästa valet för [tema]
Mode:       MOCK

----------------------------------------------------------------------

Job ID: job_20251107_110356_abc123
Status: BLOCKED

QC Report:
  Status: BLOCKED
  Issues: 2
  AutoFix: Yes
  Human Signoff Required: No

Output Files:
  - job_package: storage/output/job_..._job_package.json
  - article: storage/output/job_..._article.md
  - qc_report: storage/output/job_..._qc_report.json
  - execution_log: storage/output/job_..._execution_log.json

Python API

from src.api import run_backlink_job

result = run_backlink_job(
    publisher_domain="example-publisher.com",
    target_url="https://client.com/product-x",
    anchor_text="bästa valet för [tema]",
    mock=True  # Mock mode - no external APIs
)

# result innehåller:
# - job_id: str
# - status: 'DELIVERED' | 'BLOCKED' | 'ABORTED'
# - job_package: dict
# - article: str
# - qc_report: dict
# - execution_log: dict
# - output_files: dict (paths till sparade filer)

🧪 Tester

Alla tester körs utan externa dependencies:

1. Schema-validering

python tests/test_schema_validation.py

Validerar BacklinkJobPackage mot JSON Schema.

2. Live validering

python tests/test_live_validation.py

Validerar datakvalitet, språk-konsistens, intent alignment.

3. QC-system (Del 3A)

python tests/test_qc_system.py

7 tester:

• LSI requirements check
• Trust sources validation
• Anchor risk assessment
• Link placement rules
• Full QC validation
• AutoFixOnce limit enforcement
• Blocking conditions

4. E2E Mock Pipeline (Del 3A)

python tests/test_e2e_mock.py

7 tester:

• Full pipeline execution
• State machine transitions
• QC integration
• Output file generation
• Loop detection
• Job package schema validation
• RESCUE max once verification

Kör alla tester

python tests/test_schema_validation.py && \
python tests/test_live_validation.py && \
python tests/test_qc_system.py && \
python tests/test_e2e_mock.py

Förväntat resultat: ✅ Alla tester passar

🛡️ QC-System (Implementerat i Del 3A)

Quality Control-systemet har två nivåer:

1. Automatisk korrigering (AutoFixOnce)

Vid mindre avvikelser görs exakt EN automatisk fix:

• Flytta länk inom samma sektion
• Justera ankartyp (exact → brand/generic)
• Injicera saknade LSI (inom policy)
• Lägga till compliance-disclaimers

Alla ändringar loggas i qc_report.json → autofix_logs.

Konfiguration: config/policies.yaml

2. Blocking Conditions

Vid allvarliga avvikelser blockeras delivery och kräver human signoff:

• Intent alignment: "off"
• Trust-källor: 0 godkända
• Konkurrent-detektion i content
• Reglerad vertikal utan disclaimers
• Ankar-risk: "high"

Sätter human_signoff_required: true i QC-rapport.

Konfiguration: config/thresholds.yaml

QC-regler

Se config/thresholds.yaml för komplett regeluppsättning:

• LSI: 6-10 termer, ±2 meningar från länk
• Trust sources: T1-T4 tiers, minst 1 T1-källa
• Anchor risk: High/Medium/Low patterns
• Link placement: Ej H1/H2, mittsektion preferred
• Word count: Minimum 900 ord
• Compliance: Disclaimers för reglerade vertikaler (gambling, finance, health, legal)

📊 State Machine (Implementerat i Del 3A)

Varje körning går genom följande states:

RECEIVE → PREFLIGHT → WRITE → QC → DELIVER
                                ↓ (on QC fail)
                             RESCUE (max 1 gång)
                                ↓
                               QC → DELIVER or ABORT

Loop-skydd:

• Payload hashas efter WRITE och RESCUE
• Om identisk → ABORT (ingen förändring)

RESCUE-policy:

• Max 1 försök per körning
• Endast vid auto-fixable issues
• Vid human_signoff_required → direkt ABORT

Spårbarhet: Alla state-övergångar loggas i execution_log.json:

{
  "metadata": {
    "job_id": "job_...",
    "started_at": "2025-11-07T10:30:00Z",
    "completed_at": "2025-11-07T10:30:05Z",
    "final_state": "DELIVER"
  },
  "log_entries": [
    {
      "type": "state_transition",
      "timestamp": "...",
      "from_state": "RECEIVE",
      "to_state": "PREFLIGHT"
    },
    ...
  ]
}

📖 Dokumentation

Specifikationer

1. backlink_engine_ideal_flow.md

   • Detaljerat idealflöde från input till output
   • Beskriver alla profileringar och extensions

2. NEXT-A1-ENGINE-ADDENDUM.md

   • Formella krav för Del 2 & 3
   • QC & AutoFixOnce specifikation
   • State machine krav
   • Acceptance-kriterier

3. next-a1-spec.json

   • Komplett Next-A1 specifikation
   • Intent-klassificering
   • Bridge-typer
   • Länkplacering och ankarpolicies

JSON Schema

Single Source of Truth: backlink_job_package.schema.json

Detta schema definierar det bindande kontraktet för BacklinkJobPackage.

Obligatoriska toppnivå-fält:

• job_meta – Metadata (job_id, created_at, spec_version)
• input_minimal – Tre inputs (publisher, target, anchor)
• publisher_profile – Profilerad publishersida
• target_profile – Profilerad målsida
• anchor_profile – Ankaranalys
• serp_research_extension – SERP-research (main + cluster queries)
• intent_extension – Intent-modellering och alignment
• generation_constraints – Generationspolicies (språk, ordkrav, etc)

🎯 Acceptance-kriterier & Status

Per NEXT-A1-ENGINE-ADDENDUM.md § 7:

Del 2 (Schema & Validering)

• test_schema_validation.py passerar ✅
• test_live_validation.py passerar ✅
• README beskriver struktur och användning ✅

Del 3A (Production Infrastructure & QC)

• QC-system implementerat med AutoFixOnce ✅
• State machine loggar till execution_log ✅
• CLI och Python API fungerar ✅
• Mock-mode tillåter testing utan externa deps ✅
• test_qc_system.py passerar (7/7 tester) ✅
• test_e2e_mock.py passerar (7/7 tester) ✅
• README uppdaterad med Del 3A ✅

Del 3B (Content Generation Pipeline)

• PageProfiler kan extrahera från URLs ✅
• SERP Researcher kan fetcha & analysera SERP (Ahrefs + mock) ✅
• Intent Analyzer bygger intent_extension ✅
• Writer Engine genererar artiklar med LLM ✅
• Multi-provider LLM support (Claude, GPT, Gemini) ✅
• Multi-stage & single-shot strategies ✅
• Bridge types (strong/pivot/wrapper) implementerade ✅
• LSI-injection fungerar ✅
• LLM-enhanced profiling (anchor, entities, tone) ✅
• Full E2E-test med riktiga inputs ✅
• Batch processing system ✅
• Cost tracking and optimization ✅

Production Readiness

• Minst 1–2 manuella produktionskörningar genomförda
• Performance-tuning baserat på verklig användning
• Deployment-guide och best practices dokumenterade

🔬 Implementation Status

Version: 1.0.0-beta

Komponent	Status	Tester	Dokumentation
JSON Schema	✅ Klar	✅ 2/2	✅ Komplett
QC System	✅ Klar	✅ 7/7	✅ Komplett
State Machine	✅ Klar	✅ 7/7	✅ Komplett
Execution Logger	✅ Klar	✅ 7/7	✅ Komplett
CLI & API	✅ Klar (production)	✅ 7/7	✅ Komplett
PageProfiler	✅ Klar	✅ 14/14	✅ Komplett
SERP Researcher	✅ Klar (Ahrefs)	✅ 14/14	✅ Komplett
Writer Engine	✅ Klar (Multi-LLM)	✅ 12/12	✅ Komplett
Intent Analyzer	✅ Klar	✅ 26/26	✅ Komplett
LLM Enhancer	✅ Klar	✅ Testad	✅ Komplett
Batch Runner	✅ Klar	✅ Testad	✅ BATCH_GUIDE.md
Batch Monitor	✅ Klar	-	✅ BATCH_GUIDE.md
Batch Scheduler	✅ Klar	-	✅ BATCH_GUIDE.md

Del 3A: ✅ Komplett och testad (80/80 tester passerar) Del 3B: ✅ Komplett och produktionsklar (Live-testad med Claude Haiku)

Total test coverage: 80 passing tests

🤝 Integration

Motorn är utformad för att vara integrationsklar utan hårda beroenden.

Användningsfall

• MCP-verktyg (Model Context Protocol)
• Batch-processer för stora uppdrag
• GUI/Dashboard för manuell körning
• CI/CD pipelines för automatisk content-generering

Inga antaganden görs om externa orchestrators. Mock-mode tillåter testning av full pipeline utan externa API:er.

📝 Exempel

Se examples/example_job_package.json för ett komplett exempel på BacklinkJobPackage.

Exempel visar:

• Svensk publisher (consumer_magazine tone)
• Kommersiell målsida (Product X)
• Partial anchor med commercial_research intent
• Aligned intent mellan SERP, target och publisher
• Pivot bridge-type rekommenderad

🔄 Workflow

# 1. Klona och installera
git clone https://github.com/robwestz/BACOWR.git
cd BACOWR
pip install -r requirements.txt

# 2. Kör tester för att verifiera installation
python tests/test_qc_system.py
python tests/test_e2e_mock.py

# 3. Kör pipeline i mock-mode
python main.py \
  --publisher test.com \
  --target https://example.com \
  --anchor "test link" \
  --mock \
  --verbose

# 4. Inspektera output
ls -la storage/output/
cat storage/output/job_*_qc_report.json
cat storage/output/job_*_article.md

🐛 Troubleshooting

QC blockerar i mock-mode

Problem: Mock-artiklar innehåller ofta inte tillräckligt med trust-källor eller LSI-termer.

Förväntat beteende: QC ska blockera vid brister - detta visar att systemet fungerar korrekt.

Lösning för produktion: Implementera Del 3B (Writer Engine med LLM) som genererar fullständiga artiklar.

Tester misslyckas

# Verifiera installation
pip install -r requirements.txt

# Kör tester individuellt för att isolera problem
python tests/test_schema_validation.py
python tests/test_qc_system.py

📄 Licens

(Lägg till din licens här)

👥 Bidrag

(Lägg till bidragsinstruktioner här)

📞 Support

För frågor eller buggrapporter, öppna en issue i GitHub-repot: https://github.com/robwestz/BACOWR/issues

---

Version: 1.0.0-beta (Del 3A & 3B Komplett) Status: Production Ready with Full LLM Integration & Batch Processing Last Updated: 2025-11-07

🤖 LLM Provider Support

BACOWR supports multiple LLM providers with automatic fallback:

Provider	Models Supported	Features
Anthropic Claude	Haiku, Sonnet, Opus	✅ Tested & Working
OpenAI GPT	GPT-4o, GPT-4o-mini, GPT-4-turbo	✅ Integrated
Google Gemini	Flash, Pro 1.5, Pro 1.0	✅ Integrated

Setup

# Set at least one API key
export ANTHROPIC_API_KEY='sk-ant-...'
export OPENAI_API_KEY='sk-proj-...'
export GOOGLE_API_KEY='...'

# Optional: Ahrefs for real SERP data
export AHREFS_API_KEY='...'

See .env.example for complete configuration options.

Writing Strategies

• Multi-Stage (Best Quality): 3 LLM calls (outline → content → polish)
• Single-Shot (Fast): 1 LLM call, optimized prompt

Choose strategy based on quality vs. speed requirements.

📊 Batch Processing

Process hundreds of articles efficiently with:

• CSV/JSON input for batch job definitions
• Parallel processing with configurable workers
• Rate limiting to respect API quotas
• Cost tracking and estimation
• Live monitoring dashboard
• Scheduled batches for off-peak processing

Example:

# Process 100 articles overnight
python batch_scheduler.py \
  --input large_batch.csv \
  --chunk-size 25 \
  --time 23:00 \
  --interval 15 \
  --parallel 2 \
  --rate-limit 10

See BATCH_GUIDE.md for complete documentation.