fedora-commblog-rag

A RamaLama-powered RAG tool trained on Fedora Community Blog and Fedora Magazine articles and guidelines — helping new authors write better posts.

Overview

This project builds a Retrieval-Augmented Generation (RAG) pipeline using RamaLama on the writing guidelines and past published articles of two Fedora publications:

• Fedora Community Blog — for contributors
• Fedora Magazine — for the broader Linux community

Use case: A reviewer pastes a draft article and the model flags whether it meets editorial standards — tone, structure, topic scope, and technical accuracy.

Just want to use the tool? See docs/QUICKSTART.md — pull the pre-built images from Quay and run, no pipeline required.

---

Table of Contents

• Overview
• Quickstart (use the tool)
• Project Roadmap
  • Goal
  • Deliverables
  • Pipeline
  • Models Benchmarked
  • Success Criteria & Constraints
• Project Structure
• Setup
  • Prerequisites
  • Installation
  • Environment Variables
• Usage
  • 1. Fetch Articles
  • 2. Stage the Corpus
  • 3. Analyze Dataset Quality (optional)
  • 4. Build the RAG Vector Stores
  • 5. Push to Quay
  • 6. Run the Editorial Assistant GUI
  • 7. Benchmark Models
• Quay Repositories
• Deployment (Local OpenShift / CRC)
• Models Tested
• Evaluation
• Contributing
• License
• Attribution

---

Quickstart (use the tool)

If you just want to use the editorial assistant — not rebuild anything — pull the pre-built RAG images from Quay and run:

# Pull a model (one time)
ramalama pull hf://bartowski/google_gemma-4-E4B-it-GGUF

# Run the assistant against the CommBlog Quay image
ramalama run --rag quay.io/fedora/editorial-guide-ramalama:commblog \
  hf://bartowski/google_gemma-4-E4B-it-GGUF

No fetching, no Docling ingest, no building — the Quay images already contain the guidelines and past articles. Full instructions (including the Streamlit web UI) are in docs/QUICKSTART.md.

---

Project Roadmap

Goal

Build a RAG model trained on Fedora Community Blog and Fedora Magazine writing guidelines and past articles — to help reviewers flag whether draft posts meet standards for tone, structure, and technical accuracy.

---

Deliverables

+------------------------------------------------------------------+
|                                                                  |
|  1  Curate dataset via WordPress REST API                        |
|     ├─ Fedora Community Blog                                     |
|     └─ Fedora Magazine                                           |
|                         |                                        |
|                         v                                        |
|  2  Ingest & clean with Docling                                  |
|     └─ Supports HTML, PDF, Markdown -- feed into RamaLama        |
|                         |                                        |
|                         v                                        |
|  3  Test use case                                                |
|     └─ Paste draft -- model flags editorial issues               |
|                         |                                        |
|                         v                                        |
|  4  Collect editor feedback & iterate                            |
|     ├─ CommBlog: Michal Konecny                                  |
|     └─ Magazine: editorial team                                  |
|                         |                                        |
|                         v                                        |
|  5  Expand scope decision                                        |
|     +-- Works for Magazine --> adopt for both publications       |
|     +-- Does not fit       --> stay CommBlog-only                |
|                         |                                        |
|                         v                                        |
|  6  Write a Community Blog article summarizing the work          |
|                                                                  |
+------------------------------------------------------------------+

---

Pipeline

WordPress REST API (CommBlog + Magazine)
              |
              v
   data/raw/<source>/*.json        (metadata + index)
   data/source/<source>/*.html     (article HTML = the corpus)
              |
              +  data/guidelines/*.md  (staged into data/source/)
              |
              v  (RamaLama RAG — Docling runs internally)
   quay.io/fedora/editorial-guide-ramalama:commblog
   quay.io/fedora/editorial-guide-ramalama:magazine
   quay.io/fedora/editorial-guide-ramalama:editorial  (combined)
              |
              v
   Editorial Assistant (app.py)

Note: There is no separate Docling ingestion step. ramalama rag runs Docling internally to capture document structure directly from the article HTML, which works better than feeding it pre-flattened markdown.

---

Models Benchmarked

Model	Size	Hardware
Gemma 4 E4B	~4B	Local laptop
Granite 4 Micro	3B	Local laptop

Note: The project initially benchmarked four models (Qwen3 4B, SmolLM2 1.7B, Gemma 3 4B, Granite 7B). Following mentor guidance, the lineup was narrowed to the newer-generation Gemma 4 and Granite 4 models, which are far more memory-efficient and produce better results than their predecessors. Larger models will be revisited once dedicated GPU server hardware is provisioned.

---

Success Criteria & Constraints

Success	Tool validated by CommBlog and Magazine editors as useful for new authors
Scope	CommBlog first, then Magazine if the pipeline generalizes
Timeline	~10 weeks -- iterate on chunking size and model performance
Variables	Chunk size · overlap · model choice · system prompt

---

Project Structure

fedora-commblog-rag/
├── app.py                    # Streamlit editorial assistant GUI
├── data/
│   ├── raw/
│   │   ├── commblog/         # CommBlog JSON + index from WordPress API
│   │   └── magazine/         # Magazine JSON + index from WordPress API
│   ├── source/
│   │   ├── commblog/         # CommBlog article HTML + guidelines (RAG corpus)
│   │   └── magazine/         # Magazine article HTML + guidelines (RAG corpus)
│   ├── guidelines/
│   │   ├── commblog_guidelines.md
│   │   └── magazine_guidelines.md
│   ├── reports/             # quality_report.json per source (analysis only)
│   └── reviews/             # Saved model review outputs (good/bad examples)
├── scripts/
│   ├── fetch_articles.py     # WordPress REST API scraper -> raw JSON + source HTML
│   ├── stage_corpus.sh       # Copies guidelines into the source corpus dirs
│   ├── clean_dataset.py      # Quality-report generator (analysis only)
│   ├── benchmark.py          # Model benchmarking
│   ├── review_good_examples.sh
│   └── review_bad_examples.sh
├── models/
│   └── ramalama_config/      # RamaLama RAG config
├── notebooks/
│   └── exploration.ipynb     # Experimentation & results analysis
├── docs/
│   ├── QUICKSTART.md         # Use the tool via Quay images (no pipeline)
│   ├── GUIDE.md              # Complete step-by-step pipeline guide
│   ├── OPENSHIFT_CRC.md      # Local OpenShift (CRC) deployment guide
│   ├── COMMUNISHIFT.md       # Fedora Communishift deployment (study/practice/request)
│   ├── INFRA_APPRENTICE.md   # Step-by-step: bastion login, clone ansible, explore
│   ├── notes.md              # Dev notes & findings
│   └── blog_draft.md         # Draft of the CommBlog article
├── .gitignore
├── LICENSE
├── README.md
└── requirements.txt

RamaLama runs Docling internally during ramalama rag, so there is no separate ingestion script — the corpus is the article HTML in data/source/.

---

Setup

Prerequisites

• Python 3.10+
• RamaLama installed
• Podman installed and running
• Access to the Fedora WordPress REST APIs (no key needed for public posts)

Installation

# Clone the repo
git clone https://forge.fedoraproject.org/ai-ml/editorial-guide-ramalama.git
cd editorial-guide-ramalama

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Environment Variables

Create a .env file at the root of the project:

WP_COMMBLOG_API_URL=https://communityblog.fedoraproject.org/wp-json/wp/v2
WP_MAGAZINE_API_URL=https://fedoramagazine.org/wp-json/wp/v2
WP_API_KEY=      # Only needed if rate-limited

---

Usage

1. Fetch Articles (both sources)

python scripts/fetch_articles.py

# Or fetch individually
python scripts/fetch_articles.py --source commblog
python scripts/fetch_articles.py --source magazine

2. Stage the Corpus

Copy the guidelines into each source directory so the build includes both the editorial rules and the example articles. There is no separate Docling step — ramalama rag ingests the article HTML directly.

bash scripts/stage_corpus.sh

3. Analyze Dataset Quality (optional)

Generates a quality_report.json per source under data/reports/. This is analysis-only and does not affect the corpus.

python scripts/clean_dataset.py

# Or individually
python scripts/clean_dataset.py --source commblog
python scripts/clean_dataset.py --source magazine

4. Build the RAG Vector Stores

# CommBlog only
ramalama rag --chunk-size 100 data/source/commblog quay.io/fedora/editorial-guide-ramalama:commblog

# Magazine only
ramalama rag --chunk-size 100 data/source/magazine quay.io/fedora/editorial-guide-ramalama:magazine

# Combined
ramalama rag --chunk-size 100 data/source quay.io/fedora/editorial-guide-ramalama:editorial

Note: --chunk-size 100 keeps all chunks safely under the embedder's 512-token batch limit. Because ramalama rag runs Docling on the article HTML and chunks by document structure, chunks run larger than flattened markdown would — 200 still overflowed on this dataset, so 100 is the reliable value here.

5. Push to Quay (after building)

podman login quay.io
podman push quay.io/fedora/editorial-guide-ramalama:commblog
podman push quay.io/fedora/editorial-guide-ramalama:magazine
podman push quay.io/fedora/editorial-guide-ramalama:editorial

6. Run the Editorial Assistant GUI

streamlit run app.py

Opens at http://localhost:8501. Select the publication in the sidebar, paste a draft article, and the model flags whether it meets editorial standards.

7. Benchmark Models

python scripts/benchmark.py

---

Quay Repositories

The pre-built RAG vector stores are publicly available on Quay.io:

Image	Description
quay.io/fedora/editorial-guide-ramalama:commblog	CommBlog corpus
quay.io/fedora/editorial-guide-ramalama:magazine	Magazine corpus
quay.io/fedora/editorial-guide-ramalama:editorial	Combined corpus

---

Deployment (Local OpenShift / CRC)

The editorial assistant is being prepared to run on Fedora's Communishift (OpenShift 4.x) infrastructure. The deployment work is staged:

1. Study how Fedora deploys apps to Communishift (via Infrastructure Apprentice read-only access) — see docs/COMMUNISHIFT.md.
2. Practice the same pattern locally on CRC (OpenShift Local), the supported OpenShift 4.x tool that replaces deprecated Minishift (3.x) — see docs/OPENSHIFT_CRC.md.
3. Request a real Communishift namespace via the Fedora Forge once the deployment is proven locally.

Because the app's RAG images are already public on Quay, a Communishift deployment reduces to: project → imagestream (Quay) → deployment → service → route, with no secrets or in-cluster build needed.

CRC needs ~9–11 GB RAM, so it is resource-intensive on a typical laptop. It is intended as a learning/staging step until dedicated server hardware is provisioned.

---

Models Tested

Model	Size	Notes
Gemma 4 E4B	~4B	Recommended default; efficient, runs well locally
Granite 4 Micro (IBM)	3B	Hybrid Mamba arch, low memory, Fedora-friendly

---

Evaluation

Success is measured by workshopping the tool with Fedora Community Blog and Fedora Magazine editors to determine usefulness for new authors.

---

Contributing

This project is part of an Outreachy internship with the Fedora Project. Contributions, feedback, and suggestions are welcome!

---

License

Apache 2.0 — see LICENSE for details.

---

Attribution

Assisted-by: Claude (Anthropic)

Portions of this project's code, documentation, and data processing were developed with AI assistance. All technical decisions, testing, debugging, and validation were carried out by the author in accordance with the Fedora Policy on AI-Assisted Contributions.