packaging-guide-ramalama/AGENTS.md

AGENTS.md

Guidance for AI coding agents working on packaging-guide-ramalama. This is a RamaLama-based Retrieval-Augmented Generation (RAG) assistant that helps identify deviations from the Fedora RPM Packaging Guidelines. Think of this as a README written specifically for coding agents. For human-facing docs, see README.md and CONTRIBUTING.md.

Project overview

• Purpose: an assistant that reviews RPM spec files and packaging questions against the Fedora Packaging Guidelines using a local RAG pipeline.
• Core tech: RamaLama (RAG build and run), Docling (document conversion and chunking, used internally by RamaLama), and small open-weight GGUF models.
• Language scope: the corpus (the collection of documents the RAG system ingests and retrieves from) is scoped to Python, C, and shell packaging, the foundational languages for OS-level development in Fedora.
• Artifacts: RAG vector-store images are published to Quay and consumed by the app and CLI.

Primary data source

The Fedora Packaging Guidelines are the central data source for this project. They are the rules the assistant checks packaging work against, so they are the obvious and most important source in the corpus. The AsciiDoc source is cloned from the Fedora Forge and staged with the heaviest weight in the dataset. Everything else (the RPM Packaging Guide, the in-tree RPM Reference Manual, and real-world spec files) is supporting material around these guidelines.

Possible follow-up: it may be worth adding a git submodule for specific source content, such as the Fedora Docs packaging/guidelines sources, so the exact upstream revision is pinned in-tree. This has not been done yet and should be evaluated against the current fetch-and-stage approach.

Repository layout

• scripts/ - pipeline: fetch_sources.py -> stage_corpus.sh -> build
• data/sources.yaml - the annotated source list; single source of truth for what the corpus is built from
• data/source/ - the staged corpus that ramalama rag ingests (gitignored, rebuilt on demand)
• data/raw/ - untouched fetched material (gitignored)
• data/MANIFEST.json - per-source provenance: resolved URL, timestamp, and git commit hash (gitignored)
• tests/ - pytest suite for the fetch pipeline (network and git mocked)
• docs/ - guides (GUIDE, CONTRIBUTING)

Setup commands

On Fedora Linux, install the system dependencies first. RamaLama and Podman are not Python packages and must be installed separately.

# System dependencies (Fedora Linux)
sudo dnf install python3 python3-pip git podman ramalama

# Python dependencies for the pipeline
pip install -r requirements.txt

# Development dependencies (adds pytest)
pip install -r requirements-dev.txt

If RamaLama is not packaged for your Fedora release, it can also be installed with pip install ramalama. See https://github.com/containers/ramalama for other installation options.

Data staging (this is the current focus of the project)

The corpus is not committed. It is a build artifact, rebuilt from data/sources.yaml by a script. This keeps the repo lean and the pipeline reproducible across environments (12-Factor App, factor III: config in the environment).

# List declared sources without fetching
python scripts/fetch_sources.py --list

# Fetch a single source
python scripts/fetch_sources.py --source guidelines

# Fetch everything and print a corpus summary
bash scripts/stage_corpus.sh

Source URLs live in sources.yaml but can be overridden per source with an environment variable PGR_SOURCE_<KEY_UPPER>_URL, so locations stay out of the code. Every run rewrites data/MANIFEST.json for traceability.

Build and run

The RAG flow is two steps. First, build an OCI image from the staged corpus. Then, run queries against it.

# Build the RAG vector-store image from the staged corpus
ramalama rag --chunk-size N data/source quay.io/gtfrans2re/packaging-guide-ramalama

# Run a query (prompt is passed via stdin)
ramalama run --rag quay.io/gtfrans2re/packaging-guide-ramalama <model>

The full pipeline (fetch -> stage -> build) is documented in docs/GUIDE.md.

Important - RamaLama RAG API: the flags --model, --corpus, and --query do not exist. Building uses ramalama rag --chunk-size N <corpus_dir> <oci_image>. Querying uses ramalama run --rag <oci_image> <model> with the prompt on stdin. Do not invent flags.

Chunk size: the right value is still being determined for this corpus. Unlike the editorial mini-project (which used flattened article HTML and needed a very small chunk size), this corpus mixes AsciiDoc, Markdown, PDF, HTML, and raw spec files. Mentors have asked to evaluate smaller models with larger chunk sizes (256 or 512) once GPU access is available, since a corpus of strictly RPM guidelines may benefit from larger chunks. Always test a build end to end after changing the chunk size.

Code style

• Python: follow PEP 8, and keep functions small and readable. This is a small project, so prefer clarity over cleverness.
• Shell scripts: POSIX-friendly bash, and quote variables.
• Prose in Markdown and AsciiDoc: use the One Sentence Per Line convention. Put each sentence on its own line rather than wrapping prose at a fixed column width. Rendered output is unaffected (a single line break does not show up to the reader), but git diffs become far easier to review because a change to one sentence does not reflow the rest of the paragraph. Two consecutive line breaks still start a new paragraph.
• All files: use plain ASCII only. Do not introduce ambiguous Unicode characters such as en dashes, em dashes, curly quotes, or arrows. Use - for dashes, straight quotes, and -> for arrows. The Forge review tooling flags these.

To scan a file for ambiguous Unicode before committing:

python3 -c "
import sys
with open(sys.argv[1], encoding='utf-8') as f:
    for i, line in enumerate(f, 1):
        for ch in line:
            if ord(ch) > 127:
                print(f'Line {i}: {repr(ch)} (U+{ord(ch):04X})')
" AGENTS.md

If it prints nothing, the file is clean (pure ASCII).

Testing and verification

The pipeline has a pytest suite under tests/. Every network and git interaction is mocked, so the suite runs airgapped with no access to Forge, GitHub, dist-git, or rpm.org. Run it before finishing any change to the fetch pipeline:

# Install dev dependencies (includes pytest)
pip install -r requirements-dev.txt

# Run the suite (airgapped, no network needed)
pytest -q

Also verify what is relevant to your change:

# Confirm the source list parses and lists correctly
python scripts/fetch_sources.py --list

# Confirm the staging pipeline runs end to end (needs network)
bash scripts/stage_corpus.sh

# Confirm the manifest was written
cat data/MANIFEST.json

When you change fetch_sources.py, add or update a corresponding test. Test-driven development here is deliberate: it keeps AI-assisted changes honest and guards the pipeline against regressions.

Scan any changed file for ambiguous Unicode before committing (see Code style above).

Contribution workflow (agents must follow this)

• Never push directly to main. Create a branch and open a pull request.
• Sign off commits with DCO (git commit -s). This is encouraged as a best practice, though the FPCA already provides the legal basis.
• Disclose AI use. Add an Assisted-by: <model> <version> trailer to commits per the Fedora AI-Assisted Contributions Policy.
• Authentication: push over HTTPS following the Fedora Forge HTTP auth docs.
• Branch naming: feat/..., fix/..., docs/..., chore/....
• Commit messages: imperative mood, with a concise summary line.
• One logical change per PR. Reference related issues (e.g. Closes #123).

Security and safety notes

• Do not commit secrets, API tokens, or Quay/robot credentials.
• The published Quay images are public, so do not embed private data in the corpus.
• The corpus is built from public, appropriately licensed sources only. Each source's license is recorded in sources.yaml; do not add sources whose licensing is unclear.
• Keep changes to the RAG config (chunk size, model strings) deliberate and tested, since they directly affect output quality.

Good first pointers for agents

• data/sources.yaml is the heart of the data-prep stage. Adding or adjusting a source is usually an edit there plus, if it is a new source type, a matching fetcher in scripts/fetch_sources.py.
• When editing docs, keep repo URLs pointing at forge.fedoraproject.org/ai-ml/packaging-guide-ramalama. Leave upstream links (RamaLama, Docling, rpm.org) and Quay image paths as they are unless explicitly migrating them.

Remember

The Fedora Packaging Guidelines are the heaviest-weight source in the corpus and must stay that way unless mentors decide otherwise.