#!/usr/bin/env python3 """Build the Noema documentation section as static HTML. Usage: python3 docs/site/build.py OUTPUT_DIR Sources: the repository's Markdown documents, the OpenAPI document, the UI screenshots, and the authored pages in docs/site/pages/*.md. A page file may pull a repository document in with a line `{{include path [demote]}}`. The output follows the dixon.cx page shell (css/site.css, navy rail) with the full SEO head: indexable, canonical, Open Graph, Twitter and TechArticle JSON-LD. Every page must also be listed in the Noema block of dixon.cx's sitemap.xml. """ import html import json import os import re import shutil import sys import markdown ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")) PAGES = os.path.join(ROOT, "docs", "site", "pages") BASE = "/noema/" SITE = "https://dixon.cx" # Order, slug, title, summary. The page body comes from pages/.md. CHAPTERS = [ ("index", "Noema", "A persistent, inspectable artificial cognitive runtime: minds that remember, reason with evidence, say how sure they are, and can always show their working."), ("concepts", "Concepts and vocabulary", "Minds, events, epistemic kinds, memory kinds, beliefs, drives and the interpretation boundary."), ("architecture", "Architecture", "The daemon, the cognitive cycle, the storage model and the boundaries between deterministic code and language models."), ("configuration", "Cognitive configuration", "The per-mind settings that shape a mind: workspace capacity, attention weights, budgets and background cognition."), ("personality", "Identity and personality", "Versioned personalities, templates, traits and how they modulate attention and voice."), ("cognition", "The cognitive cycle", "Processes, attention scoring, the global workspace, executive dispatch, modes and metacognition."), ("memory", "Memory", "Episodic, semantic, procedural and autobiographical memory; retrieval, decay, consolidation and provenance."), ("beliefs", "Beliefs and evidence", "Evidence-derived scores, what the numbers mean, statuses including unknown, temporal scope, source reliability, contradictions and operator corrections."), ("epistemics", "Epistemic honesty", "The 0.2 review: assertions before beliefs, evidence provenance, honest scores, unknowns, time, reliability, reproducible replay and redaction."), ("conversation", "Conversation", "How a message becomes an observation, a perception, a response intent and finally language."), ("motivation", "Goals, drives and affect", "The goal tree, the closed drive set, rule-driven affect and how they bias attention."), ("predictions", "Predictions and calibration", "Explicit predictions with criteria, deterministic resolution, prediction error and calibration."), ("graph", "Relationship graph", "Entities, evidenced edges, merges and the canvas explorer."), ("llm-providers", "Language models", "Roles, providers (OpenAI-compatible, Anthropic, Ollama, Amazon Bedrock), per-mind routing, budgets, recorded calls, replay and versioned prompts."), ("capabilities", "Capabilities and policy", "The only path to action: ALLOW / ASK / DENY, approvals, locked capabilities and tool output as data."), ("volition", "Volition", "Wants, intentions and commitments as distinct recorded states: generation, conflicts, formation, reconsideration and values."), ("planning", "Planning and execution", "Plans as validated graphs of typed steps, observe-act-verify, replanning, capability negotiation and bounded host operations."), ("agency", "Agency and why", "Authority outside cognition, the causal chain from want to outcome, attribution and forensic explanations."), ("integrations", "Integrations", "Research folder, git mirrors, Prometheus and signed webhooks as provenance-tagged observations."), ("dreaming", "Dreaming", "The opt-in idle mode: replay, association and speculative hypotheses that can never act."), ("snapshots-replay", "Snapshots, forks, replay and experiments", "Capturing state, branching minds, re-running cognition under a recorded runtime identity, and comparing forks that differ in one thing, including the model."), ("cognitive-research", "Cognitive research", "Operational definitions, ablations, introspection accuracy, calibration, agency metrics and the research dashboard, with no claim of consciousness."), ("ui-tour", "Interface tour", "Every screen of the web interface, what it shows and what an operator does there."), ("api", "HTTP API", "Authentication, roles, the error envelope, streaming and every route."), ("cli", "Command line", "What an operator can do from a terminal: every command, with examples."), ("security", "Security and threat model", "Trust boundaries, secret handling, sessions, two-factor authentication and the threat-by-threat verification table."), ("privacy", "Privacy and redaction", "Append-only history and the one audited path that removes content while keeping its shape."), ("decisions", "Architecture decision records", "The recorded decisions and the alternatives they rejected."), ("development", "How it was built", "The phased plan, what each phase delivered, measured performance, release notes and changelog."), ("glossary", "Glossary", "Short definitions of every term used across the documentation."), ] STYLE = """ """ HEAD = """ {titletag} | Andy Dixon {style} Skip to content

""" TAIL = """

""" # dixon.cx house style: plain ASCII punctuation on every published page. PLAIN = str.maketrans({"\u2014": "-", "\u2013": "-", "\u2018": "'", "\u2019": "'", "\u201c": '"', "\u201d": '"', "\u2026": "..."}) LINK_MAP = { "ARCHITECTURE.md": "architecture", "SECURITY.md": "security", "THREAT_MODEL.md": "security", "PLAN.md": "development", "CONTRIBUTING.md": "development", "CHANGELOG.md": "development", "README.md": "index", "docs/interpretation.md": "concepts", "docs/configuration.md": "configuration", "docs/ENVIRONMENT.md": "configuration", "docs/personality.md": "personality", "docs/cognition.md": "cognition", "docs/memory.md": "memory", "docs/beliefs.md": "beliefs", "docs/conversation.md": "conversation", "docs/motivation.md": "motivation", "docs/predictions.md": "predictions", "docs/graph.md": "graph", "docs/llm-providers.md": "llm-providers", "docs/capabilities.md": "capabilities", "docs/integrations.md": "integrations", "docs/dreaming.md": "dreaming", "docs/snapshots-replay.md": "snapshots-replay", "docs/performance.md": "development", "docs/RELEASE_NOTES.md": "development", "docs/privacy.md": "privacy", "docs/epistemics.md": "epistemics", "docs/volition.md": "volition", "docs/planning.md": "planning", "docs/agency.md": "agency", "docs/cognitive-research.md": "cognitive-research", "docs/openapi.json": "api", "docs/adr": "decisions", } def read(path): with open(os.path.join(ROOT, path), encoding="utf-8") as f: return f.read() def demote(md, levels): out = [] fence = False for line in md.split("\n"): if line.startswith("```"): fence = not fence if not fence and line.startswith("#"): line = "#" * levels + line out.append(line) return "\n".join(out) def strip_h1(md): lines = md.split("\n") for i, l in enumerate(lines): if l.startswith("# "): return "\n".join(lines[:i] + lines[i + 1:]) return md def expand(md): """Resolve {{include path [demote N] [keep-title]}} and {{openapi}} directives.""" def inc(m): parts = m.group(1).split() path = parts[0] body = read(path) d = 0 keep = False for p in parts[1:]: if p.startswith("demote"): d = int(p.split("=")[1]) if "=" in p else 1 if p == "keep-title": keep = True if not keep: body = strip_h1(body) if d: body = demote(body, d) return body md = re.sub(r"\{\{include ([^}]+)\}\}", inc, md) md = md.replace("{{openapi}}", openapi_markdown()) return md def rewrite_links(html_text): def fix(m): href = m.group(1) if href.startswith(("http://", "https://", "#", "mailto:", "/")): return m.group(0) anchor = "" if "#" in href: href, anchor = href.split("#", 1) anchor = "#" + anchor if href.startswith("docs/screenshots/"): return 'href="' + BASE + "img/" + os.path.basename(href) + '"' for k, v in LINK_MAP.items(): if href == k or href.rstrip("/") == k or href.startswith(k + "/"): return 'href="' + BASE + v + anchor + '"' if href.endswith(".md"): slug = os.path.splitext(os.path.basename(href))[0] return 'href="' + BASE + slug + anchor + '"' return m.group(0) html_text = re.sub(r'href="([^"]+)"', fix, html_text) html_text = re.sub(r'src="docs/screenshots/([^"]+)"', r'src="' + BASE + r'img/\1"', html_text) return html_text def openapi_markdown(): doc = json.loads(read("internal/api/openapi.json")) groups = {} for path, ops in doc["paths"].items(): for method, op in ops.items(): tag = (op.get("tags") or ["root"])[0] groups.setdefault(tag, []).append((path, method.upper(), op)) out = [] for tag in sorted(groups): out.append(f"\n### {tag}\n") out.append("| Method | Path | Minimum role | Operation |\n|---|---|---|---|") for path, method, op in sorted(groups[tag], key=lambda x: (x[0], x[1])): role = str(op.get("x-required-role", "")).replace("(", "").replace(")", "") summary = op.get("summary", op.get("operationId", "")) out.append(f"| `{method}` | `{path}` | {role} | {summary} |") return "\n".join(out) + "\n" def render_page(idx, slug, title, summary, md): md = expand(md) conv = markdown.Markdown(extensions=["tables", "fenced_code", "toc", "sane_lists", "attr_list", "def_list", "md_in_html"], extension_configs={"toc": {"toc_depth": "2-3"}}) body = conv.convert(md) body = rewrite_links(body) body = re.sub(r"", '

', body).replace("

", "") # Split into section boxes at h2 boundaries. parts = re.split(r"(?=

(.*?)

', sec, re.S) if not m: boxes.append('

' + sec + "

") continue hid, htext = m.group(1), m.group(2) headings.append((hid, re.sub("<[^>]+>", "", htext))) rest = sec[m.end():] boxes.append(f'

{htext}

{rest}

') contents = "" if headings: contents = '

{html.escape(title)}

{html.escape(summary)}

{intro} {contents}

''' canonical = SITE + BASE + ("" if slug == "index" else slug) ld = {"@context": "https://schema.org", "@type": "TechArticle", "headline": title, "description": summary, "author": {"@type": "Person", "name": "Andy Dixon", "url": SITE + "/"}, "publisher": {"@type": "Person", "name": "Andy Dixon", "url": SITE + "/"}, "mainEntityOfPage": canonical, "inLanguage": "en-GB"} if slug != "index": ld["isPartOf"] = {"@type": "CreativeWork", "name": "Noema", "url": SITE + BASE} jsonld = "\n".join("\t\t" + l for l in json.dumps(ld, indent=2, ensure_ascii=False).replace("

(.*?)

{htext}

On this page

Noema documentation

{html.escape(title)}