NG911 RFC Catalog

A static site (MkDocs + Python tools) that lists, categorizes, and summarizes NG911-relevant RFCs. Pages are generated from a small seed file, enriched with metadata from RFC Editor / IETF Datatracker, and (optionally) augmented with AI summaries.

---

Requirements

• Python 3.10+
• pip (or uv, pipx, etc.)
• An OpenAI API key only if you want to generate summaries (the repo ships with prebuilt derived/ and summaries/ so you can explore without calling any APIs)

---

Installation

# 1) Create and activate a virtualenv
python -m venv .venv
source .venv/bin/activate

# 2) Install the project (editable) + dev extras
pip install -e .[dev]

# 3) Copy the config template and edit it
cp .env.sample .env
# then edit .env (see Configuration below)

---

Configuration

All configuration lives in .env. A template .env.sample is included.

Minimum settings to enable summaries:

OPENAI_API_KEY=sk-...                 # your key (required only if summarizing)
RFCSITE_SUMMARY_ENABLED=1              # gate to enable the summarizer
RFCSITE_SUMMARY_MODEL=gpt-4o           # any text-capable model you have
RFCSITE_SUMMARY_PROMPT_ID=mpt_...      # your stored prompt ID
RFCSITE_SUMMARY_PROMPT_VERSION=1       # your stored prompt version

HTTP/cache knobs (optional):

RFCSITE_CACHE_DIR=.cache/http
RFCSITE_CACHE_TTL=0        # 0=revalidate via ETag/Last-Modified; >0 TTL seconds; -1 never revalidate
RFCSITE_TIMEOUT=20

---

ChatGPT / OpenAI setup

1. API Key. Create one in your OpenAI account and set OPENAI_API_KEY in .env.
2. Stored Prompt. This project uses a stored prompt (a reusable instruction object) rather than inlining instructions.
   • A sample prompt is included at data/prompt.sample.json to show the expected content/shape.
   • Create a stored prompt in your own workspace that emits the required JSON:

     {
       "summary_tagline": "...",
       "problems": "...",
       "contributions": "...",
       "ng911_stage": "..."
     }

   • Put its identifiers into .env:

     RFCSITE_SUMMARY_PROMPT_ID=mpt_...
     RFCSITE_SUMMARY_PROMPT_VERSION=1
     

3. Model. Set RFCSITE_SUMMARY_MODEL (e.g., gpt-4o). Token/character counts are computed for cost planning.

You can skip all of this and still build the site using the checked-in derived/ and summaries/.

---

Commands

All commands are exposed via the rfcsite CLI (installed by pip install -e .).

1) Derive metadata (derived/)

rfcsite derive

• Fetches/merges RFC Editor + Datatracker metadata.
• Computes plaintext character and token estimates.
• Writes derived/rfcNNNN.json.

Uses an on-disk HTTP cache (.cache/http) so repeated runs don’t hammer upstream.

2) Summarize RFCs (summaries/)

# Single RFC
rfcsite summarize --rfc 4119

# Multiple RFCs (comma-separated or repeated flags)
rfcsite summarize --rfc 4119,6442,5986
rfcsite summarize --rfc 4119 --rfc 6442 --rfc 5986

# Overwrite existing summaries
rfcsite summarize --rfc 4119 --force

• Sends the entire RFC plaintext to your stored prompt.
• Writes summaries/rfcNNNN.md containing a single JSON object with the fields above.
• The RFC page generator renders a “Summary (Generated with AI)” section using those fields.

3) Build / Serve the site

# One-off build to site/
rfcsite build

# Dev server with live reload
rfcsite serve

• Page generators in docs_gen/ create per-RFC pages under rfc/ (virtual docs tree) and a catalog page grouped by categories.
• The site uses MkDocs Material with a few CSS tweaks in docs/assets/styles.css.

4) Cache inspection (optional)

rfcsite ls-cache                 # table
rfcsite ls-cache --json | jq .   # machine-readable

---

Data lifecycle

1. Edit the catalog: data/seed-index.json (fields: rfc, title, categories, priority, summary).
2. Refresh metadata: rfcsite derive → updates derived/.
3. Refresh AI summaries: rfcsite summarize → updates summaries/.
4. Rebuild site: rfcsite build or rfcsite serve.

Regeneration-friendly: derived/ and summaries/ are checked in so users can experiment without fetching or calling OpenAI. You can delete and regenerate at any time:

rm -rf derived/ summaries/ .cache/http/ site/
rfcsite derive
rfcsite summarize --rfc 4119,6442,5986
rfcsite build

---

Validation

• Seed index schema: seed-index.schema.json validates renamed fields (categories, summary) and removed fields (wg, urls).
• Derived record schema: derived-rfc.schema.json validates merged metadata, provenance, and token/char counts.

Run your preferred validator (e.g., jsonschema) in CI or locally.

---

How the build works (high level)

1. Derive collects RFC metadata and writes derived/rfc*.json.
2. Summarize (optional) writes summaries/rfc*.md (JSON payloads).
3. MkDocs build runs generator scripts (docs_gen/) that:
   • Create per-RFC pages (title, status, dates, canonical links, token estimates).
   • Inject the AI summary fields.
   • Build the catalog page grouped by category, with a short tagline under each item.

---

Troubleshooting

• Summaries not appearing Ensure summaries/rfcNNNN.md exists and is valid JSON (no stray text outside the object). Rebuild after generating.

• 401/403 from OpenAI Check OPENAI_API_KEY is visible to the process. Try:

  python -c "import os; print(bool(os.getenv('OPENAI_API_KEY')))"

• Slow builds / rate limits Verify the HTTP cache is populating: rfcsite ls-cache. Keep RFCSITE_CACHE_TTL=0 to revalidate cheaply via ETag/Last-Modified.

---

Contributing

• Add or correct entries in data/seed-index.json.
• Improve generators in docs_gen/.
• Keep PRs small and include a rfcsite derive && rfcsite build run before pushing to catch schema/link issues.

---

What's in this repository

data/
  seed-index.json           # human-maintained catalog (categories, priority, one-line summary)
  prompt.sample.json        # example stored prompt content/shape for OpenAI
derived/                    # generated per-RFC JSON (safe to delete; can be regenerated)
summaries/                  # generated AI summaries as JSON-in-MD (safe to delete; can be regenerated)
docs/                       # MkDocs content (home/about/assets); RFC pages are generated at build
docs_gen/                   # build-time generators (mkdocs-gen-files): rfc pages, catalog, nav
tools/                      # CLI + libraries (HTTP cache, fetchers, summarizer, settings)
mkdocs.yml                  # site configuration (Material theme, plugins)
.env.sample                 # configuration template to copy to .env
README.md                   # this file