https://yusupov.cloud/api.php?action=feedcontributions&feedformat=atom&user=MvuijlstYusupov's House - User contributions [en-gb]2026-05-16T10:04:48ZUser contributionsMediaWiki 1.44.0https://yusupov.cloud/index.php?title=Inrik_%C3%9Cksk%C3%BCla&diff=441Inrik Üksküla2026-05-06T13:37:51Z<p>Mvuijlst: </p>
<hr />
<div>'''Inrik Üksküla''' (born 1979) is an Estonian linguist and semiotician, currently unaffiliated. He studied theoretical linguistics and logic at the University of Tartu, where he subsequently taught for several years before leaving academic employment in 2018. He has described his departure as voluntary, citing a preference for "work that doesn't require committee approval." He has since published independently, maintaining a particular interest in formal models of small, restricted corpora.<br />
<br />
Üksküla's approach is characterised by a willingness to develop competing hypotheses in parallel rather than committing prematurely to a single reading. He has credited the Tartu tradition of semiotics associated with Juri Lotman as an influence on his view that a corpus should be allowed to generate its own interpretive possibilities before external frameworks are applied.<br />
<br />
==Work==<br />
Üksküla's preprint "The Clan of Zagi: Numeric Calculus or Genealogical Primer? A Structural Analysis of the Kristiansen Cuneiform Corpus" (2024) analysed 104 short, highly formulaic sentences in the [[Zagi Tablets]]—a corpus of clay tablets inscribed in the [[Kristiansen coding system]] and headed in Akkadian as ''imri Zagi-ak'' ("the clan of Zagi"). The study identified a small set of structural pivots and a paradigm of four ordinal or cardinal markers, and developed two interpretive hypotheses: a numeric calculus reading, in which the corpus functions as a didactic arithmetic system, and a genealogical primer reading, in which the same structures encode a kinship model for the named clan. Üksküla evaluated both against the corpus and concluded that the available evidence did not decisively favour either, proposing a hybrid in which formal numeric notation is used to model the internal structure of a specific kin-group.<br />
<br />
The Akkadian heading ''imri Zagi-ak'' attracted particular attention as the first named attribution in the broader [[Kristiansen corpus]]. Üksküla noted that the name Zagi does not appear in any known Akkadian administrative context and may be a transliteration of a name from an unrelated language.<br />
<br />
[[Ginevra Rubergskier|Rubergskier]] has observed that the AND_PLUS element in the Zagi corpus shares its collocational profile with the addition operator she identified in the [[Dozenal Primer Inscription]], a correspondence Üksküla discusses briefly in his preprint. [[Marie Roelandt]] subsequently developed Üksküla's genealogical hypothesis further in two posts on her blog [[Klema Field Notes]], arguing that the UNIT sign should be read as the kin term CHILD.<br />
<br />
==See also==<br />
* [[Zagi Tablets]]<br />
* [[Scapula Glyph Inscription]]<br />
* [[Jan-Tage Kristiansen]]<br />
* [[Marie Roelandt]]<br />
<br />
[[Category:Researchers]][[Category:Epigraphy]][[Category:Kristiansen corpus]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=A_Cabinet_of_Brief_Curiosities&diff=415A Cabinet of Brief Curiosities2026-04-23T15:24:51Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| 01_name = A Cabinet of Brief Curiosities<br />
| 02_url = https://acbc.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2025<br />
| 05_genre = AI-generated short-fiction application<br />
| 06_language = Python<br />
| 07_framework = [[Flask]] 3.0<br />
| 08_license = MIT<br />
}}<br />
<br />
'''A Cabinet of Brief Curiosities''' (abbreviated '''acbc''') is a web application hosted at <code>acbc.yusupov.cloud</code> that generates illustrated three-sentence short stories in the style of [[H. P. Lovecraft]]. Each story is composed by a large language model from a structured set of randomised "knobs" and optional user-supplied seed words, and is paired with a black-and-white illustration produced by a generative image model and styled to resemble a 19th-century engraved book plate. The site's rotating tagline — drawn every thirty minutes from a pool of forty-five variants — frames the act of generation in deliberately archaic terms; the canonical opening reads "Dredge slivers of impossible worlds from the black gulfs of imagination and press them into trembling mortal words."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Flask 3.0 with [[SQLite]] as its database, accessed through [[SQLAlchemy]].<ref name="requirements">requirements.txt in the project repository </ref> Authentication is handled by Flask-Login and cross-site request forgery protection by Flask-WTF. It is deployed on an Ubuntu VPS behind [[Nginx]] with [[Gunicorn]] running over a Unix socket under a dedicated <code>django</code> system user, supervised by systemd. Additional dependencies include the [[OpenAI]] Python client for both text and image generation, [[Pillow (imaging library)|Pillow]] for image post-processing, [[python-dotenv]] for environment configuration, and [[httpx]] as the underlying HTTP transport. The front end is rendered from Jinja templates using a small Bootstrap-derived stylesheet (<code>static/style.css</code>) and is registered as an installable progressive web app via <code>static/manifest.json</code> and a service worker (<code>static/sw.js</code>).<br />
<br />
== Data model ==<br />
<br />
The database contains two tables.<br />
<br />
=== User ===<br />
<br />
<code>User</code> stores a single bootstrapped administrator account with an e-mail address, a Werkzeug password hash, and a creation timestamp. Sign-ups are disabled at the route level: the <code>/signup</code> endpoint flashes a notice and redirects to login. The administrator is created on application start from the <code>ADMIN_EMAIL</code> and <code>ADMIN_PASSWORD</code> environment variables if no matching row exists.<br />
<br />
=== Story ===<br />
<br />
<code>Story</code> stores the generated short fiction:<br />
<br />
* ''id'' (primary key), an optional ''user_id'' foreign key (null for guest submissions), the three-sentence ''story_text'', the optional ''mood'', ''nouns'' and ''verbs'' seeds supplied by the requester, an optional ''image_path'' (relative to the static folder, e.g. <code>images/story_42.png</code>), the originating ''ip_address'' (indexed), an indexed ''created_at'' timestamp, and a JSON-encoded ''knobs_json'' column that records the parameter set the model was given.<br />
<br />
The schema is created on first run by SQLAlchemy. A small startup routine inspects the live table and issues an <code>ALTER TABLE</code> if a newer column (such as <code>knobs_json</code>) is missing, providing a lightweight migration path without an external migration framework. The same routine sets <code>PRAGMA journal_mode=WAL</code> on the SQLite database to allow concurrent reads while a background image-generation thread writes.<br />
<br />
== Story generation pipeline ==<br />
<br />
Story generation is initiated by a POST to <code>/generate</code> and proceeds through several deterministic-and-random stages before the OpenAI call.<br />
<br />
=== Seeds and knobs ===<br />
<br />
A request may carry up to three optional free-text fields — ''noun'', ''verb'', and ''mood'' — which are passed to the model as "seeds" and validated for presence in the output. Around the seeds, the application constructs a compact JSON ''knobs'' object that nudges the model along several axes:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Dimension !! Pool size !! Examples<br />
|-<br />
| Perspective || 4 || first, second, third, omniscient<br />
|-<br />
| Structure || 8 || Discovery → Investigation → Revelation; Object → Rumor → Catastrophe; Signal → Interpretation → Realization; …<br />
|-<br />
| Time || 8 (forced ''ambiguous'') || Victorian era, distant past, mythic period, interwar, near-future of obsolete technology<br />
|-<br />
| Location || 50 || lighthouse, salt marsh, foundry, signal box, scriptorium, observatory, shipbreaker's yard, …<br />
|-<br />
| Situation || 32 || during a storm, at low tide, during a blackout, on the eve of demolition, while the clock refuses to strike, …<br />
|-<br />
| Lexical palette || 53 || nautical, horological, astronomical, archival, cartographic, mycological, glaciological, heraldic, …<br />
|-<br />
| Style constraint || 5 || include exactly one short line of dialogue; include a question; avoid the words "shadow" and "dim"; …<br />
|-<br />
| Sentence pattern || 3 || short → long → medium; medium → short → long; long → medium → short<br />
|-<br />
| Theme (only when no seeds) || 18 || forbidden knowledge, cosmic entities, inherited curses, mathematical theorems, astronomical observations, …<br />
|}<br />
<br />
The knobs object always carries the seeds and at most two additional non-seed dimensions. Three of the knobs — ''perspective'', ''structure'', and ''time'' — are selected ''deterministically'' from a SHA-256 hash of a salt composed of the current 30-minute time bucket, the requester's IP address, and the seed words; this guarantees that the same client requesting the same seeds inside the same half-hour window draws the same priority knobs. The previous story's knobs for that IP are read from the <code>knobs_json</code> column (falling back to the JSONL choices log for older rows) and avoided where possible. ''Time'' is hard-pinned to <code>ambiguous</code> to suppress dated or era-specific references in the output. Lexicon and constraint values are sampled with the regular pseudo-random generator. Once all priority knobs are forced into the object, any non-priority extras are dropped at random until at most two non-seed knobs remain.<br />
<br />
=== System rules ===<br />
<br />
The system prompt is composed entirely of positive instructions: it asks for exactly three sentences in a grave Lovecraftian register, with no titles, lists, numbering, or blank lines, and embeds two short hand-written exemplar stories so the model can imitate length, cadence, and concreteness rather than reason in the negative. The application then validates the response against a separate banned-word list rather than naming forbidden terms in the prompt itself, in order to avoid the well-documented tendency of language models to reproduce items they are explicitly told to avoid.<br />
<br />
=== Model selection ===<br />
<br />
The default text model is GPT-4o (configurable via <code>OPENAI_MODEL</code>) with a configurable fallback (<code>OPENAI_FALLBACK_MODEL</code>, also GPT-4o by default). A helper function inspects the installed OpenAI SDK at request time: if the configured model is in the <code>gpt-5</code> family but the SDK does not expose the Responses API, the call silently falls back to a chat-compatible model. When the Responses API is available it is preferred for all models, with the system rules supplied via the explicit <code>instructions</code> field. For <code>gpt-5</code> family models the call additionally injects a <code>reasoning</code> object (defaulting to ''effort: low'' but configurable via <code>OPENAI_REASONING_EFFORT</code>), drops the <code>temperature</code> and <code>top_p</code> parameters (which those models reject), and grants a higher <code>max_output_tokens</code> budget (1600 by default, raised to 2400 on retry) to absorb reasoning-token consumption. For non-reasoning models, ''temperature'' is sampled uniformly from a narrow [0.78, 0.92] interval and ''top_p'' is fixed at 0.9, deliberately tighter than typical creative-writing defaults to keep tone consistent. Where the Responses API is unavailable, the call degrades to Chat Completions.<br />
<br />
=== Validation and retry ===<br />
<br />
After the call returns, the output is validated by a checker that enforces:<br />
<br />
* Exactly three non-empty lines.<br />
* No line beginning with any of a list of banned opening prefixes ("In the", "Beneath", "Under the", "Within the", and so on).<br />
* Absence of a curated list of overused or out-of-register words and phrases ("eldritch", "cyclopean", "loathsome", any inflection of ''tentacle'', and similar).<br />
* Absence of anachronisms unsuited to the desired ambiguous-historical tone (kilometres, kilograms, GPS coordinates, e-mail addresses, four-digit years, references to Wi-Fi).<br />
* A per-sentence word count in the [8, 60] range.<br />
* One terminal punctuation mark per line.<br />
<br />
If the request supplied seeds, a second pass verifies that the noun appears in the text — with allowance for irregular plurals — and that the verb appears in any common inflection.<br />
<br />
A separate near-duplicate check computes a 64-bit SimHash of the candidate text and rejects it if the Hamming distance to any of the most recent fifty stored stories is below a small threshold, so the corpus does not collapse into thematic loops.<br />
<br />
When validation fails, a single targeted retry is issued with a corrective prompt that quotes the failing lines back at the model verbatim, names the specific failures, lowers the temperature slightly, and reuses the same knobs JSON. The retry result is accepted if it passes, or if it fails with strictly fewer issues than the original. If the model call itself fails — including the specific case where a <code>gpt-5</code> response is marked ''incomplete'' due to <code>max_output_tokens</code> — the pipeline retries once with a higher token budget, then attempts the configured fallback model, and finally falls back to a fixed three-sentence placeholder. All failures surface to the user as Flask flash messages with appropriate severity.<br />
<br />
=== Persistence and logging ===<br />
<br />
The validated story text is written to a new <code>Story</code> row together with the seeds, the originating IP, and the JSON-encoded knobs object. Image generation is then dispatched in a background daemon thread so the HTTP response returns immediately. Two structured logs are appended in JSON-Lines format under the Flask instance folder:<br />
<br />
* <code>instance/choices.log.jsonl</code> records, per story, the seeds, the knobs JSON, the selected temperature and top_p, the model actually used, the configured model, and the validation outcome (including reasons and whether a retry was attempted).<br />
* <code>instance/image.log.jsonl</code> records each image generation attempt with status (''success'', ''retry'', ''failed'', ''skipped''), error text, attempt count, image size, image model, and post-processing diagnostics such as the standard deviation of the output's luminance.<br />
<br />
Both logs are rotated to a single ''<file>.1'' backup once they exceed a configurable byte threshold (default 2 MiB) so that long-running instances cannot fill the disk.<br />
<br />
== Image generation ==<br />
<br />
Each story is paired with a square 1024×1024 illustration generated through the OpenAI image API.<br />
<br />
=== Style library ===<br />
<br />
The application maintains a curated library of fifteen monochrome illustration styles, each anchored to one or more named historical artists or movements — for example wood engravings in the manner of Gustave Doré or Thomas Bewick, pen-and-ink in the manner of Aubrey Beardsley or Edward Gorey, drypoint in the manner of Käthe Kollwitz, aquatint in the manner of Goya's ''Caprichos'', a Victorian scientific plate after Ernst Haeckel, relief woodcut after Lynd Ward, silhouette cuts after Lotte Reiniger, and symbolist pen-and-ink after Alfred Kubin. Anchoring each entry to a real reference reliably moves the model closer to the desired register. The style for a given story is selected by hashing its primary key, so adjacent stories on the home grid do not visually collide and a regenerated image for the same story can vary by perturbing the salt. A legacy global counter file at <code>instance/image_style_cycle.txt</code> is retained for callers without a story id.<br />
<br />
=== Prompt construction ===<br />
<br />
To keep the image prompt concrete enough for a diffusion model to act on, the three-sentence story is first reduced to a one- or two-sentence visual scene description by a cheap secondary call to a smaller model (<code>OPENAI_SCENE_MODEL</code>, default <code>gpt-4o-mini</code>); the helper names a single subject, a single setting, one source of light, and one telling object, and discards mood words and metaphor. The final image prompt is then assembled from a hard full-bleed directive, the selected style sentence, the scene description, and an avoid clause that explicitly forbids colour, painterly shading, photorealism, captions, watermarks, signatures, and any kind of border, frame, or decorative edge.<br />
<br />
=== Image API and retries ===<br />
<br />
The configured image model defaults to <code>gpt-image-1</code>; common typos such as <code>gpt-image-1.5</code> are normalised back to <code>gpt-image-1</code> at start-up. The generation size is configurable through <code>OPENAI_IMAGE_GEN_SIZE</code> (default 1024×1024) and the post-processed final size is fixed at 1024×1024. Each generation tolerates up to three attempts (configurable via <code>IMAGE_RETRIES</code>) with exponential backoff starting at 1.5 seconds and capped at 10 seconds. If all attempts fail — or if a returned image is blank or near-uniform — a small inline SVG placeholder is written to disk and recorded as the story's image path so the front end always has something to display. A few legacy stories carry a one-pixel GIF placeholder of the same purpose; the application detects either by the presence of the substring <code>_placeholder.</code> in the path.<br />
<br />
=== Post-processing ===<br />
<br />
Successfully returned PNG bytes are passed through a Pillow-based post-processor that:<br />
<br />
* Estimates the background colour from the four corner patches.<br />
* Computes a difference image against a uniform background of that colour, raises its contrast, and finds the bounding box of meaningful content.<br />
* Crops away any uniform border of more than ten pixels on any side, padded by two pixels to avoid clipping ink.<br />
* Resizes the result back to the final size using Lanczos resampling and re-encodes as optimised PNG.<br />
* Computes the standard deviation of the resulting image's luminance; if the value falls below a small threshold, the image is treated as blank and the generation attempt is failed so a retry can be issued.<br />
<br />
If Pillow is unavailable or any step fails, the original bytes are written through unchanged.<br />
<br />
== Public interface ==<br />
<br />
=== Home ===<br />
<br />
The home page (<code>/</code>) renders the generation form together with a gallery of the five most recent stories that successfully produced an image. For unauthenticated visitors, the form is hidden and replaced by a rotating notice (one of twenty-two phrasings, selected from a SHA-256 hash of the visitor's IP and a six-hour bucket) when the visitor has already generated a story in the last 24 hours or when the site-wide guest cap has been reached. A footer-level statistics block displays the number of guest stories in the last 24 hours, the number of stories created by signed-in users in the same window, the all-time total, and the time elapsed since the most recent story.<br />
<br />
=== Story detail ===<br />
<br />
Each story is reachable at <code>/story/<id></code> and is publicly viewable regardless of authorship. The page presents the three sentences alongside the illustration; for the administrator, controls are exposed to regenerate the image (<code>/regenerate-image/<id></code>) or delete the story (<code>/story/<id>/delete</code>). A polling endpoint at <code>/api/story/<id>/status</code> returns a JSON document indicating whether a real image has yet been written, the URL of the image (or placeholder), and a flag distinguishing the two; the front-end script polls with exponential backoff capped at eight seconds, gives up after a hard timeout, and writes status updates into an <code>aria-live</code> region for screen-reader accessibility. The story page also overrides the base template's [[Open Graph protocol|Open Graph]] block to advertise per-story metadata, including the generated illustration, when the page is shared on social media.<br />
<br />
=== Archive ===<br />
<br />
The archive (<code>/archive</code>) is a paginated chronological listing of all stories, nine per page, with previous/next navigation. There is no per-user filter — all stories are visible. The archive page sets <code>&lt;meta name="robots" content="noindex,follow"&gt;</code> to keep the long tail out of search-engine indexes while leaving individual story pages indexable.<br />
<br />
=== Health endpoint ===<br />
<br />
<code>/healthz</code> returns a small JSON document and an HTTP 200 when the application is fully configured and able to query the database, or HTTP 503 when the OpenAI API key is not set or the database round-trip fails. It is intended for use by uptime monitors and load balancers.<br />
<br />
=== Authentication ===<br />
<br />
<code>/login</code> accepts only the e-mail address configured in <code>ADMIN_EMAIL</code> and verifies the password against the stored Werkzeug hash. <code>/logout</code> ends the session. <code>/signup</code> is intentionally disabled. All form-bearing pages carry a CSRF token rendered from the Flask-WTF helper, and an expired token is recovered with a flash message and a redirect rather than an HTTP error.<br />
<br />
=== Tagline rotation ===<br />
<br />
The base template injects a "current tagline" string into every response. The selection is deterministic on the current 30-minute interval since the Unix epoch: the interval timestamp is used as a seed for the standard library random module, which then picks one of forty-five variant phrasings. All visitors served within the same half-hour see the same tagline; the tagline rotates without any database state.<br />
<br />
== Rate limiting ==<br />
<br />
Rate limiting is enforced for unauthenticated visitors only:<br />
<br />
* '''Per-IP daily limit''': any IP that has produced a story within the last 24 hours is blocked from generating another (one story per visitor per day).<br />
* '''Site-wide guest cap''': the total number of guest-authored stories in the last 24 hours must not exceed <code>GUEST_DAILY_CAP</code> (default 24). When the cap is reached, the form is hidden for all guests until older stories age out.<br />
<br />
Both limits are evaluated at form render time (to hide the form) and at form submission time (to short-circuit the POST with a flashed warning and a redirect). Authenticated users have no rate limits and no per-IP enforcement.<br />
<br />
The originating IP for limit accounting and for the <code>Story.ip_address</code> column is read from the <code>X-Forwarded-For</code> request header only when the immediate peer is in a configurable trusted-proxy allow-list (<code>TRUSTED_PROXIES</code>, default loopback); otherwise the application uses <code>request.remote_addr</code>. This prevents trivial spoofing of the originating address when the application is exposed without a reverse proxy in front of it.<br />
<br />
== Deployment ==<br />
<br />
The production deployment is an Ubuntu VPS running a systemd unit (<code>acbc.service</code>) that launches Gunicorn with three workers, bound to a Unix domain socket under the project directory. Nginx terminates HTTPS (provisioned by [[Let's Encrypt]] via Certbot), serves the <code>static/</code> directory directly with a one-year immutable cache header, and proxies all other requests to the Gunicorn socket. The service runs as the <code>django</code> system user out of <code>/home/django/acbc</code>. The application reads its configuration from environment variables loaded via python-dotenv.<br />
<br />
== Security and authorisation ==<br />
<br />
* All POST endpoints require a CSRF token issued by Flask-WTF.<br />
* Sign-ups are disabled; only the bootstrapped administrator account can authenticate.<br />
* Login attempts for any e-mail other than <code>ADMIN_EMAIL</code> are rejected without a database query.<br />
* The image-deletion helper refuses to remove any path that does not begin with <code>images/</code> or that, after canonicalisation, falls outside the configured upload folder, providing protection against path-traversal in stored data.<br />
* Story deletion requires either the administrator session or ownership of the row; image regeneration requires the administrator session.<br />
* The story-status JSON endpoint returns no user-identifying information beyond the public fields rendered on the story page.<br />
* The originating-IP determination only honours <code>X-Forwarded-For</code> from trusted proxies.<br />
<br />
== See also ==<br />
<br />
* [[OpenAI]]<br />
* [[Flask (web framework)]]<br />
* [[H. P. Lovecraft]]<br />
* [[Computational creativity]]<br />
* [[Generative artificial intelligence]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=A_Cabinet_of_Brief_Curiosities&diff=414A Cabinet of Brief Curiosities2026-04-23T15:23:51Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| 01_name = A Cabinet of Brief Curiosities<br />
| 02_url = https://acbc.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2025<br />
| 05_genre = AI-generated short-fiction application<br />
| 06_language = Python<br />
| 07_framework = [[Flask]] 3.0<br />
| 08_license = MIT<br />
}}<br />
<br />
'''A Cabinet of Brief Curiosities''' (abbreviated '''acbc''') is a web application hosted at <code>acbc.yusupov.cloud</code> that generates illustrated three-sentence short stories in the style of [[H. P. Lovecraft]]. Each story is composed by a large language model from a structured set of randomised "knobs" and optional user-supplied seed words, and is paired with a black-and-white illustration produced by a generative image model and styled to resemble a 19th-century engraved book plate. The site's rotating tagline — drawn every thirty minutes from a pool of forty-five variants — frames the act of generation in deliberately archaic terms; the canonical opening reads "Dredge slivers of impossible worlds from the black gulfs of imagination and press them into trembling mortal words."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Flask 3.0 with [[SQLite]] as its database, accessed through [[SQLAlchemy]] (Flask-SQLAlchemy 3.1).<ref name="requirements">requirements.txt in the project repository pins Flask 3.0.3, Flask-Login 0.6.3, Flask-SQLAlchemy 3.1.1, Flask-WTF ≥1.2, python-dotenv 1.0.1, openai ≥1.50, httpx 0.27.2, and Pillow ≥10.</ref> Authentication is handled by Flask-Login and cross-site request forgery protection by Flask-WTF. It is deployed on an Ubuntu VPS behind [[Nginx]] with [[Gunicorn]] running over a Unix socket under a dedicated <code>django</code> system user, supervised by systemd. Additional dependencies include the [[OpenAI]] Python client for both text and image generation, [[Pillow (imaging library)|Pillow]] for image post-processing, [[python-dotenv]] for environment configuration, and [[httpx]] as the underlying HTTP transport. The front end is rendered from Jinja templates using a small Bootstrap-derived stylesheet (<code>static/style.css</code>) and is registered as an installable progressive web app via <code>static/manifest.json</code> and a service worker (<code>static/sw.js</code>).<br />
<br />
== Data model ==<br />
<br />
The database contains two tables.<br />
<br />
=== User ===<br />
<br />
<code>User</code> stores a single bootstrapped administrator account with an e-mail address, a Werkzeug password hash, and a creation timestamp. Sign-ups are disabled at the route level: the <code>/signup</code> endpoint flashes a notice and redirects to login. The administrator is created on application start from the <code>ADMIN_EMAIL</code> and <code>ADMIN_PASSWORD</code> environment variables if no matching row exists.<br />
<br />
=== Story ===<br />
<br />
<code>Story</code> stores the generated short fiction:<br />
<br />
* ''id'' (primary key), an optional ''user_id'' foreign key (null for guest submissions), the three-sentence ''story_text'', the optional ''mood'', ''nouns'' and ''verbs'' seeds supplied by the requester, an optional ''image_path'' (relative to the static folder, e.g. <code>images/story_42.png</code>), the originating ''ip_address'' (indexed), an indexed ''created_at'' timestamp, and a JSON-encoded ''knobs_json'' column that records the parameter set the model was given.<br />
<br />
The schema is created on first run by SQLAlchemy. A small startup routine inspects the live table and issues an <code>ALTER TABLE</code> if a newer column (such as <code>knobs_json</code>) is missing, providing a lightweight migration path without an external migration framework. The same routine sets <code>PRAGMA journal_mode=WAL</code> on the SQLite database to allow concurrent reads while a background image-generation thread writes.<br />
<br />
== Story generation pipeline ==<br />
<br />
Story generation is initiated by a POST to <code>/generate</code> and proceeds through several deterministic-and-random stages before the OpenAI call.<br />
<br />
=== Seeds and knobs ===<br />
<br />
A request may carry up to three optional free-text fields — ''noun'', ''verb'', and ''mood'' — which are passed to the model as "seeds" and validated for presence in the output. Around the seeds, the application constructs a compact JSON ''knobs'' object that nudges the model along several axes:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Dimension !! Pool size !! Examples<br />
|-<br />
| Perspective || 4 || first, second, third, omniscient<br />
|-<br />
| Structure || 8 || Discovery → Investigation → Revelation; Object → Rumor → Catastrophe; Signal → Interpretation → Realization; …<br />
|-<br />
| Time || 8 (forced ''ambiguous'') || Victorian era, distant past, mythic period, interwar, near-future of obsolete technology<br />
|-<br />
| Location || 50 || lighthouse, salt marsh, foundry, signal box, scriptorium, observatory, shipbreaker's yard, …<br />
|-<br />
| Situation || 32 || during a storm, at low tide, during a blackout, on the eve of demolition, while the clock refuses to strike, …<br />
|-<br />
| Lexical palette || 53 || nautical, horological, astronomical, archival, cartographic, mycological, glaciological, heraldic, …<br />
|-<br />
| Style constraint || 5 || include exactly one short line of dialogue; include a question; avoid the words "shadow" and "dim"; …<br />
|-<br />
| Sentence pattern || 3 || short → long → medium; medium → short → long; long → medium → short<br />
|-<br />
| Theme (only when no seeds) || 18 || forbidden knowledge, cosmic entities, inherited curses, mathematical theorems, astronomical observations, …<br />
|}<br />
<br />
The knobs object always carries the seeds and at most two additional non-seed dimensions. Three of the knobs — ''perspective'', ''structure'', and ''time'' — are selected ''deterministically'' from a SHA-256 hash of a salt composed of the current 30-minute time bucket, the requester's IP address, and the seed words; this guarantees that the same client requesting the same seeds inside the same half-hour window draws the same priority knobs. The previous story's knobs for that IP are read from the <code>knobs_json</code> column (falling back to the JSONL choices log for older rows) and avoided where possible. ''Time'' is hard-pinned to <code>ambiguous</code> to suppress dated or era-specific references in the output. Lexicon and constraint values are sampled with the regular pseudo-random generator. Once all priority knobs are forced into the object, any non-priority extras are dropped at random until at most two non-seed knobs remain.<br />
<br />
=== System rules ===<br />
<br />
The system prompt is composed entirely of positive instructions: it asks for exactly three sentences in a grave Lovecraftian register, with no titles, lists, numbering, or blank lines, and embeds two short hand-written exemplar stories so the model can imitate length, cadence, and concreteness rather than reason in the negative. The application then validates the response against a separate banned-word list rather than naming forbidden terms in the prompt itself, in order to avoid the well-documented tendency of language models to reproduce items they are explicitly told to avoid.<br />
<br />
=== Model selection ===<br />
<br />
The default text model is GPT-4o (configurable via <code>OPENAI_MODEL</code>) with a configurable fallback (<code>OPENAI_FALLBACK_MODEL</code>, also GPT-4o by default). A helper function inspects the installed OpenAI SDK at request time: if the configured model is in the <code>gpt-5</code> family but the SDK does not expose the Responses API, the call silently falls back to a chat-compatible model. When the Responses API is available it is preferred for all models, with the system rules supplied via the explicit <code>instructions</code> field. For <code>gpt-5</code> family models the call additionally injects a <code>reasoning</code> object (defaulting to ''effort: low'' but configurable via <code>OPENAI_REASONING_EFFORT</code>), drops the <code>temperature</code> and <code>top_p</code> parameters (which those models reject), and grants a higher <code>max_output_tokens</code> budget (1600 by default, raised to 2400 on retry) to absorb reasoning-token consumption. For non-reasoning models, ''temperature'' is sampled uniformly from a narrow [0.78, 0.92] interval and ''top_p'' is fixed at 0.9, deliberately tighter than typical creative-writing defaults to keep tone consistent. Where the Responses API is unavailable, the call degrades to Chat Completions.<br />
<br />
=== Validation and retry ===<br />
<br />
After the call returns, the output is validated by a checker that enforces:<br />
<br />
* Exactly three non-empty lines.<br />
* No line beginning with any of a list of banned opening prefixes ("In the", "Beneath", "Under the", "Within the", and so on).<br />
* Absence of a curated list of overused or out-of-register words and phrases ("eldritch", "cyclopean", "loathsome", any inflection of ''tentacle'', and similar).<br />
* Absence of anachronisms unsuited to the desired ambiguous-historical tone (kilometres, kilograms, GPS coordinates, e-mail addresses, four-digit years, references to Wi-Fi).<br />
* A per-sentence word count in the [8, 60] range.<br />
* One terminal punctuation mark per line.<br />
<br />
If the request supplied seeds, a second pass verifies that the noun appears in the text — with allowance for irregular plurals — and that the verb appears in any common inflection.<br />
<br />
A separate near-duplicate check computes a 64-bit SimHash of the candidate text and rejects it if the Hamming distance to any of the most recent fifty stored stories is below a small threshold, so the corpus does not collapse into thematic loops.<br />
<br />
When validation fails, a single targeted retry is issued with a corrective prompt that quotes the failing lines back at the model verbatim, names the specific failures, lowers the temperature slightly, and reuses the same knobs JSON. The retry result is accepted if it passes, or if it fails with strictly fewer issues than the original. If the model call itself fails — including the specific case where a <code>gpt-5</code> response is marked ''incomplete'' due to <code>max_output_tokens</code> — the pipeline retries once with a higher token budget, then attempts the configured fallback model, and finally falls back to a fixed three-sentence placeholder. All failures surface to the user as Flask flash messages with appropriate severity.<br />
<br />
=== Persistence and logging ===<br />
<br />
The validated story text is written to a new <code>Story</code> row together with the seeds, the originating IP, and the JSON-encoded knobs object. Image generation is then dispatched in a background daemon thread so the HTTP response returns immediately. Two structured logs are appended in JSON-Lines format under the Flask instance folder:<br />
<br />
* <code>instance/choices.log.jsonl</code> records, per story, the seeds, the knobs JSON, the selected temperature and top_p, the model actually used, the configured model, and the validation outcome (including reasons and whether a retry was attempted).<br />
* <code>instance/image.log.jsonl</code> records each image generation attempt with status (''success'', ''retry'', ''failed'', ''skipped''), error text, attempt count, image size, image model, and post-processing diagnostics such as the standard deviation of the output's luminance.<br />
<br />
Both logs are rotated to a single ''<file>.1'' backup once they exceed a configurable byte threshold (default 2 MiB) so that long-running instances cannot fill the disk.<br />
<br />
== Image generation ==<br />
<br />
Each story is paired with a square 1024×1024 illustration generated through the OpenAI image API.<br />
<br />
=== Style library ===<br />
<br />
The application maintains a curated library of fifteen monochrome illustration styles, each anchored to one or more named historical artists or movements — for example wood engravings in the manner of Gustave Doré or Thomas Bewick, pen-and-ink in the manner of Aubrey Beardsley or Edward Gorey, drypoint in the manner of Käthe Kollwitz, aquatint in the manner of Goya's ''Caprichos'', a Victorian scientific plate after Ernst Haeckel, relief woodcut after Lynd Ward, silhouette cuts after Lotte Reiniger, and symbolist pen-and-ink after Alfred Kubin. Anchoring each entry to a real reference reliably moves the model closer to the desired register. The style for a given story is selected by hashing its primary key, so adjacent stories on the home grid do not visually collide and a regenerated image for the same story can vary by perturbing the salt. A legacy global counter file at <code>instance/image_style_cycle.txt</code> is retained for callers without a story id.<br />
<br />
=== Prompt construction ===<br />
<br />
To keep the image prompt concrete enough for a diffusion model to act on, the three-sentence story is first reduced to a one- or two-sentence visual scene description by a cheap secondary call to a smaller model (<code>OPENAI_SCENE_MODEL</code>, default <code>gpt-4o-mini</code>); the helper names a single subject, a single setting, one source of light, and one telling object, and discards mood words and metaphor. The final image prompt is then assembled from a hard full-bleed directive, the selected style sentence, the scene description, and an avoid clause that explicitly forbids colour, painterly shading, photorealism, captions, watermarks, signatures, and any kind of border, frame, or decorative edge.<br />
<br />
=== Image API and retries ===<br />
<br />
The configured image model defaults to <code>gpt-image-1</code>; common typos such as <code>gpt-image-1.5</code> are normalised back to <code>gpt-image-1</code> at start-up. The generation size is configurable through <code>OPENAI_IMAGE_GEN_SIZE</code> (default 1024×1024) and the post-processed final size is fixed at 1024×1024. Each generation tolerates up to three attempts (configurable via <code>IMAGE_RETRIES</code>) with exponential backoff starting at 1.5 seconds and capped at 10 seconds. If all attempts fail — or if a returned image is blank or near-uniform — a small inline SVG placeholder is written to disk and recorded as the story's image path so the front end always has something to display. A few legacy stories carry a one-pixel GIF placeholder of the same purpose; the application detects either by the presence of the substring <code>_placeholder.</code> in the path.<br />
<br />
=== Post-processing ===<br />
<br />
Successfully returned PNG bytes are passed through a Pillow-based post-processor that:<br />
<br />
* Estimates the background colour from the four corner patches.<br />
* Computes a difference image against a uniform background of that colour, raises its contrast, and finds the bounding box of meaningful content.<br />
* Crops away any uniform border of more than ten pixels on any side, padded by two pixels to avoid clipping ink.<br />
* Resizes the result back to the final size using Lanczos resampling and re-encodes as optimised PNG.<br />
* Computes the standard deviation of the resulting image's luminance; if the value falls below a small threshold, the image is treated as blank and the generation attempt is failed so a retry can be issued.<br />
<br />
If Pillow is unavailable or any step fails, the original bytes are written through unchanged.<br />
<br />
== Public interface ==<br />
<br />
=== Home ===<br />
<br />
The home page (<code>/</code>) renders the generation form together with a gallery of the five most recent stories that successfully produced an image. For unauthenticated visitors, the form is hidden and replaced by a rotating notice (one of twenty-two phrasings, selected from a SHA-256 hash of the visitor's IP and a six-hour bucket) when the visitor has already generated a story in the last 24 hours or when the site-wide guest cap has been reached. A footer-level statistics block displays the number of guest stories in the last 24 hours, the number of stories created by signed-in users in the same window, the all-time total, and the time elapsed since the most recent story.<br />
<br />
=== Story detail ===<br />
<br />
Each story is reachable at <code>/story/<id></code> and is publicly viewable regardless of authorship. The page presents the three sentences alongside the illustration; for the administrator, controls are exposed to regenerate the image (<code>/regenerate-image/<id></code>) or delete the story (<code>/story/<id>/delete</code>). A polling endpoint at <code>/api/story/<id>/status</code> returns a JSON document indicating whether a real image has yet been written, the URL of the image (or placeholder), and a flag distinguishing the two; the front-end script polls with exponential backoff capped at eight seconds, gives up after a hard timeout, and writes status updates into an <code>aria-live</code> region for screen-reader accessibility. The story page also overrides the base template's [[Open Graph protocol|Open Graph]] block to advertise per-story metadata, including the generated illustration, when the page is shared on social media.<br />
<br />
=== Archive ===<br />
<br />
The archive (<code>/archive</code>) is a paginated chronological listing of all stories, nine per page, with previous/next navigation. There is no per-user filter — all stories are visible. The archive page sets <code>&lt;meta name="robots" content="noindex,follow"&gt;</code> to keep the long tail out of search-engine indexes while leaving individual story pages indexable.<br />
<br />
=== Health endpoint ===<br />
<br />
<code>/healthz</code> returns a small JSON document and an HTTP 200 when the application is fully configured and able to query the database, or HTTP 503 when the OpenAI API key is not set or the database round-trip fails. It is intended for use by uptime monitors and load balancers.<br />
<br />
=== Authentication ===<br />
<br />
<code>/login</code> accepts only the e-mail address configured in <code>ADMIN_EMAIL</code> and verifies the password against the stored Werkzeug hash. <code>/logout</code> ends the session. <code>/signup</code> is intentionally disabled. All form-bearing pages carry a CSRF token rendered from the Flask-WTF helper, and an expired token is recovered with a flash message and a redirect rather than an HTTP error.<br />
<br />
=== Tagline rotation ===<br />
<br />
The base template injects a "current tagline" string into every response. The selection is deterministic on the current 30-minute interval since the Unix epoch: the interval timestamp is used as a seed for the standard library random module, which then picks one of forty-five variant phrasings. All visitors served within the same half-hour see the same tagline; the tagline rotates without any database state.<br />
<br />
== Rate limiting ==<br />
<br />
Rate limiting is enforced for unauthenticated visitors only:<br />
<br />
* '''Per-IP daily limit''': any IP that has produced a story within the last 24 hours is blocked from generating another (one story per visitor per day).<br />
* '''Site-wide guest cap''': the total number of guest-authored stories in the last 24 hours must not exceed <code>GUEST_DAILY_CAP</code> (default 24). When the cap is reached, the form is hidden for all guests until older stories age out.<br />
<br />
Both limits are evaluated at form render time (to hide the form) and at form submission time (to short-circuit the POST with a flashed warning and a redirect). Authenticated users have no rate limits and no per-IP enforcement.<br />
<br />
The originating IP for limit accounting and for the <code>Story.ip_address</code> column is read from the <code>X-Forwarded-For</code> request header only when the immediate peer is in a configurable trusted-proxy allow-list (<code>TRUSTED_PROXIES</code>, default loopback); otherwise the application uses <code>request.remote_addr</code>. This prevents trivial spoofing of the originating address when the application is exposed without a reverse proxy in front of it.<br />
<br />
== Deployment ==<br />
<br />
The production deployment is an Ubuntu VPS running a systemd unit (<code>acbc.service</code>) that launches Gunicorn with three workers, bound to a Unix domain socket under the project directory. Nginx terminates HTTPS (provisioned by [[Let's Encrypt]] via Certbot), serves the <code>static/</code> directory directly with a one-year immutable cache header, and proxies all other requests to the Gunicorn socket. The service runs as the <code>django</code> system user out of <code>/home/django/acbc</code>. The application reads its configuration from environment variables loaded via python-dotenv.<br />
<br />
== Security and authorisation ==<br />
<br />
* All POST endpoints require a CSRF token issued by Flask-WTF.<br />
* Sign-ups are disabled; only the bootstrapped administrator account can authenticate.<br />
* Login attempts for any e-mail other than <code>ADMIN_EMAIL</code> are rejected without a database query.<br />
* The image-deletion helper refuses to remove any path that does not begin with <code>images/</code> or that, after canonicalisation, falls outside the configured upload folder, providing protection against path-traversal in stored data.<br />
* Story deletion requires either the administrator session or ownership of the row; image regeneration requires the administrator session.<br />
* The story-status JSON endpoint returns no user-identifying information beyond the public fields rendered on the story page.<br />
* The originating-IP determination only honours <code>X-Forwarded-For</code> from trusted proxies.<br />
<br />
== See also ==<br />
<br />
* [[OpenAI]]<br />
* [[Flask (web framework)]]<br />
* [[H. P. Lovecraft]]<br />
* [[Computational creativity]]<br />
* [[Generative artificial intelligence]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=A_Cabinet_of_Brief_Curiosities&diff=413A Cabinet of Brief Curiosities2026-04-23T14:50:46Z<p>Mvuijlst: Created page with "{{Infobox | 01_name = A Cabinet of Brief Curiosities | 02_url = https://acbc.yusupov.cloud | 03_developer = Michel Vuijlsteke | 04_released = 2025 | 05_genre = AI-generated short-fiction application | 06_language = Python | 07_framework = Flask 3.0 | 08_license = MIT }} '''A Cabinet of Brief Curiosities''' (abbreviated '''acbc''') is a web application hosted at <code>acbc.yusupov.cloud</code> that generates illustrated thre..."</p>
<hr />
<div>{{Infobox<br />
| 01_name = A Cabinet of Brief Curiosities<br />
| 02_url = https://acbc.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2025<br />
| 05_genre = AI-generated short-fiction application<br />
| 06_language = Python<br />
| 07_framework = [[Flask]] 3.0<br />
| 08_license = MIT<br />
}}<br />
<br />
'''A Cabinet of Brief Curiosities''' (abbreviated '''acbc''') is a web application hosted at <code>acbc.yusupov.cloud</code> that generates illustrated three-sentence short stories in the style of [[H. P. Lovecraft]]. Each story is composed by a large language model from a structured set of randomised "knobs" and optional user-supplied seed words, and is paired with a black-and-white illustration designed to resemble a 19th-century engraved book plate. The site's rotating tagline — drawn every thirty minutes from a pool of forty-five variants — frames the act of generation in deliberately archaic terms; the canonical opening reads "Dredge slivers of impossible worlds from the black gulfs of imagination and press them into trembling mortal words."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Flask 3.0 with [[SQLite]] as its database, accessed through [[SQLAlchemy]] (Flask-SQLAlchemy 3.1).<ref name="requirements">requirements.txt in the project repository pins Flask 3.0.3, Flask-Login 0.6.3, Flask-SQLAlchemy 3.1.1, python-dotenv 1.0.1, openai ≥1.50, httpx 0.27.2, and Pillow ≥10.</ref> Authentication is handled by Flask-Login. It is deployed on an Ubuntu VPS behind [[Nginx]] with [[Gunicorn]] running over a Unix socket under a dedicated <code>django</code> system user, supervised by systemd. Additional dependencies include the [[OpenAI]] Python client for both text and image generation, [[Pillow (imaging library)|Pillow]] for image post-processing, [[python-dotenv]] for environment configuration, and [[httpx]] as the underlying HTTP transport. The front end is rendered from Jinja templates using a small Bootstrap-derived stylesheet (<code>static/style.css</code>) and is registered as an installable progressive web app via <code>static/manifest.json</code> and a service worker (<code>static/sw.js</code>).<br />
<br />
== Data model ==<br />
<br />
The database contains two tables.<br />
<br />
=== User ===<br />
<br />
<code>User</code> stores a single bootstrapped administrator account with an e-mail address, a Werkzeug password hash, and a creation timestamp. Sign-ups are disabled at the route level: the <code>/signup</code> endpoint flashes a notice and redirects to login. The administrator is created on application start from the <code>ADMIN_EMAIL</code> and <code>ADMIN_PASSWORD</code> environment variables if no matching row exists.<br />
<br />
=== Story ===<br />
<br />
<code>Story</code> stores the generated short fiction:<br />
<br />
* ''id'' (primary key), an optional ''user_id'' foreign key (null for guest submissions), the three-sentence ''story_text'', the optional ''mood'', ''nouns'' and ''verbs'' seeds supplied by the requester, an optional ''image_path'' (relative to the static folder, e.g. <code>images/story_42.png</code>), the originating ''ip_address'' (indexed), and an indexed ''created_at'' timestamp.<br />
<br />
== Story generation pipeline ==<br />
<br />
Story generation is initiated by a POST to <code>/generate</code> and proceeds through several deterministic-and-random stages before the OpenAI call.<br />
<br />
=== Seeds and knobs ===<br />
<br />
A request may carry up to three optional free-text fields — ''noun'', ''verb'', and ''mood'' — which are passed to the model as "seeds" and validated for presence in the output. Around the seeds, the application constructs a compact JSON ''knobs'' object that nudges the model along several axes:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Dimension !! Pool size !! Examples<br />
|-<br />
| Perspective || 4 || first, second, third, omniscient<br />
|-<br />
| Structure || 8 || Discovery → Investigation → Revelation; Object → Rumor → Catastrophe; Signal → Interpretation → Realization; …<br />
|-<br />
| Time || 8 (forced ''ambiguous'') || Victorian era, distant past, mythic period, interwar, near-future of obsolete technology<br />
|-<br />
| Location || 50 || lighthouse, salt marsh, foundry, signal box, scriptorium, observatory, shipbreaker's yard, …<br />
|-<br />
| Situation || 32 || during a storm, at low tide, during a blackout, on the eve of demolition, while the clock refuses to strike, …<br />
|-<br />
| Lexical palette || 53 || nautical, horological, astronomical, archival, cartographic, mycological, glaciological, heraldic, …<br />
|-<br />
| Style constraint || 5 || include exactly one short line of dialogue; include a question; avoid the words "shadow" and "dim"; …<br />
|-<br />
| Sentence pattern || 3 || short → long → medium; medium → short → long; long → medium → short<br />
|-<br />
| Theme (only when no seeds) || 18 || forbidden knowledge, cosmic entities, inherited curses, mathematical theorems, astronomical observations, …<br />
|}<br />
<br />
The knobs object always carries the seeds and at most three additional dimensions. Three of the knobs — ''perspective'', ''structure'', and ''time'' — are selected ''deterministically'' from a SHA-256 hash of a salt composed of the current 30-minute time bucket, the requester's IP address, and the seed words; this guarantees that the same client requesting the same seeds inside the same half-hour window draws the same priority knobs. The previous story's knobs for that IP are read from the choices log and avoided where possible. ''Time'' is hard-pinned to <code>ambiguous</code> to suppress dated or era-specific references in the output. Lexicon and constraint values are sampled with the regular pseudo-random generator. Once all priority knobs are forced into the object, any non-priority extras are dropped at random until at most three non-seed knobs remain.<br />
<br />
=== System rules ===<br />
<br />
The system prompt instructs the model to produce a coherent short story of exactly three sentences in the style of H. P. Lovecraft, with no titles, lists, numbering, or blank lines. The tone must be grave, ominous, and unsettling, and never humorous. The model is forbidden to use the words "eldritch", "cyclopean", or "loathsome", and is forbidden to begin any line with one of six banned openings — "In the", "Beneath", "Under the", "Within the", "In the dim", and "In the shadow". Whimsical seeds are to be adapted with synonyms that preserve tone.<br />
<br />
=== Model selection ===<br />
<br />
The default text model is GPT-4o (configurable via <code>OPENAI_MODEL</code>) with a configurable fallback (<code>OPENAI_FALLBACK_MODEL</code>, also GPT-4o by default). A helper function inspects the installed OpenAI SDK at request time: if the configured model is in the <code>gpt-5</code> family but the SDK does not expose the Responses API, the call silently falls back to a chat-compatible model. When the Responses API is available it is preferred for all models, with the system rules supplied via the explicit <code>instructions</code> field. For <code>gpt-5</code> family models the call additionally injects a <code>reasoning</code> object (defaulting to ''effort: low'' but configurable via <code>OPENAI_REASONING_EFFORT</code>), drops the <code>temperature</code> and <code>top_p</code> parameters (which those models reject), and grants a higher <code>max_output_tokens</code> budget (1600 by default, raised to 2400 on retry) to absorb reasoning-token consumption. For non-reasoning models, ''temperature'' is sampled uniformly from [0.88, 1.05] and ''top_p'' is fixed at 0.92. Where the Responses API is unavailable, the call degrades to Chat Completions.<br />
<br />
=== Validation and retry ===<br />
<br />
After the call returns, the output is validated by a lightweight checker that enforces:<br />
<br />
* Exactly three non-empty lines.<br />
* No line beginning with any of the banned opening prefixes.<br />
* Absence of the banned words.<br />
* One terminal punctuation mark per line (no missing terminator, no more than two strong delimiters).<br />
<br />
If the request supplied seeds, a second pass verifies that the noun appears in the text and that the verb (or a simple inflection thereof) appears as a whole word.<br />
<br />
When validation fails, a single targeted retry is issued with a corrective prompt that names the specific failures, lowers the temperature slightly, and reuses the same knobs JSON. The retry result is accepted if it passes, or if it fails with strictly fewer issues than the original. If the model call itself fails — including the specific case where a <code>gpt-5</code> response is marked ''incomplete'' due to <code>max_output_tokens</code> — the pipeline retries once with a higher token budget, then attempts the configured fallback model, and finally falls back to a fixed three-sentence placeholder ("The moon borrowed a suitcase from a bewildered pigeon. …"). All failures surface to the user as Flask flash messages with appropriate severity.<br />
<br />
=== Persistence and logging ===<br />
<br />
The validated story text is written to a new <code>Story</code> row together with the seeds and originating IP. Image generation is then dispatched in a background daemon thread so the HTTP response returns immediately. Two structured logs are appended in JSON-Lines format under the Flask instance folder:<br />
<br />
* <code>instance/choices.log.jsonl</code> records, per story, the seeds, the knobs JSON, the selected temperature and top_p, the model actually used, the configured model, and the validation outcome (including reasons and whether a retry was attempted).<br />
* <code>instance/image.log.jsonl</code> records each image generation attempt with status (''success'', ''retry'', ''failed'', ''skipped''), error text, attempt count, image size, and image model.<br />
<br />
== Image generation ==<br />
<br />
Each story is paired with a square 1024×1024 illustration generated through the OpenAI image API.<br />
<br />
=== Style cycling ===<br />
<br />
The application maintains a counter file at <code>instance/image_style_cycle.txt</code> that walks deterministically through a library of fifteen monochrome engraving styles, including Victorian wood engraving, antique grimoire pen-and-ink, penny-dreadful frontispiece, steel engraving, copperplate etching, drypoint, mezzotint, aquatint-grained etching, scratchboard, Victorian scientific plate, woodcut, scanned 1860s book plate, fin-de-siècle symbolism, and Victorian reportage sketch. A threading lock guards the read-modify-write of the counter so that concurrent generations do not collide on the same style. If the counter file is missing or unreadable, a random style is chosen instead.<br />
<br />
=== Prompt construction ===<br />
<br />
The image prompt is assembled from four blocks:<br />
<br />
# A composition directive specifying a square 1:1 aspect ratio, full-bleed framing with no borders or margins, and a centred subject.<br />
# The selected style sentence from the cycling library.<br />
# A "scanned 1860s book plate" line that asks for slight ink unevenness and faint paper texture.<br />
# The story text itself, truncated to 900 characters with an ellipsis if longer.<br />
# A trailing "Avoid:" clause that explicitly forbids colour, grayscale wash, painterly shading, photorealism, 3D rendering, borders, frames, mats, vignettes, modern comic or anime style, halftone dots, captions, readable text, watermarks, and signatures.<br />
<br />
=== Image API and retries ===<br />
<br />
The configured image model defaults to <code>gpt-image-1</code>; common typos such as <code>gpt-image-1.5</code> are normalised back to <code>gpt-image-1</code> at start-up. The output size is fixed at 1024×1024. Each generation tolerates up to three attempts (configurable via <code>IMAGE_RETRIES</code>) with exponential backoff starting at 1.5 seconds and capped at 10 seconds. If all attempts fail, a tiny placeholder GIF is written to disk under the name <code>story_<id>_placeholder.gif</code> and recorded as the story's image path so the front end always has something to display.<br />
<br />
=== Post-processing ===<br />
<br />
Successfully returned PNG bytes are passed through a Pillow-based post-processor that:<br />
<br />
* Estimates the background colour from the four corner patches.<br />
* Computes a difference image against a uniform background of that colour, raises its contrast, and finds the bounding box of meaningful content.<br />
* Crops away any uniform border of more than ten pixels on any side, padded by two pixels to avoid clipping ink.<br />
* Resizes the result back to 1024×1024 using Lanczos resampling and re-encodes as optimised PNG.<br />
<br />
If Pillow is unavailable or any step fails, the original bytes are written through unchanged.<br />
<br />
== Public interface ==<br />
<br />
=== Home ===<br />
<br />
The home page (<code>/</code>) renders the generation form together with a gallery of the five most recent stories that successfully produced an image. For unauthenticated visitors, the form is hidden and replaced by a rotating notice (one of twenty-two phrasings, selected from a SHA-256 hash of the visitor's IP and a six-hour bucket) when the visitor has already generated a story in the last 24 hours or when the site-wide guest cap has been reached. A footer-level statistics block displays the number of guest stories in the last 24 hours, the number of stories created by signed-in users in the same window, the all-time total, and the time elapsed since the most recent story.<br />
<br />
=== Story detail ===<br />
<br />
Each story is reachable at <code>/story/<id></code> and is publicly viewable regardless of authorship. The page presents the three sentences alongside the illustration; for the administrator, controls are exposed to regenerate the image (<code>/regenerate-image/<id></code>) or delete the story (<code>/story/<id>/delete</code>). A polling endpoint at <code>/api/story/<id>/status</code> returns a JSON document indicating whether a real image has yet been written, the URL of the image (or placeholder), and a flag distinguishing the two; the front end uses this to swap a placeholder GIF for the final image once background generation completes.<br />
<br />
=== Archive ===<br />
<br />
The archive (<code>/archive</code>) is a paginated chronological listing of all stories, nine per page, with previous/next navigation. There is no per-user filter — all stories are visible.<br />
<br />
=== Authentication ===<br />
<br />
<code>/login</code> accepts only the e-mail address configured in <code>ADMIN_EMAIL</code> and verifies the password against the stored Werkzeug hash. <code>/logout</code> ends the session. <code>/signup</code> is intentionally disabled.<br />
<br />
=== Tagline rotation ===<br />
<br />
The base template injects a "current tagline" string into every response. The selection is deterministic on the current 30-minute interval since the Unix epoch: the interval timestamp is used as a seed for the standard library random module, which then picks one of forty-five variant phrasings. All visitors served within the same half-hour see the same tagline; the tagline rotates without any database state.<br />
<br />
== Rate limiting ==<br />
<br />
Rate limiting is enforced for unauthenticated visitors only:<br />
<br />
* '''Per-IP daily limit''': any IP that has produced a story within the last 24 hours is blocked from generating another (one story per visitor per day).<br />
* '''Site-wide guest cap''': the total number of guest-authored stories in the last 24 hours must not exceed <code>GUEST_DAILY_CAP</code> (default 24). When the cap is reached, the form is hidden for all guests until older stories age out.<br />
<br />
Both limits are evaluated at form render time (to hide the form) and at form submission time (to short-circuit the POST with a flashed warning and a redirect). Authenticated users have no rate limits and no per-IP enforcement.<br />
<br />
The originating IP for limit accounting and for the <code>Story.ip_address</code> column is read from <code>X-Forwarded-For</code> when the request carries it (taking the first comma-separated value), and from <code>request.remote_addr</code> otherwise.<br />
<br />
The application reads its configuration from environment variables loaded via python-dotenv:<br />
<br />
== Deployment ==<br />
<br />
The production deployment is an Ubuntu VPS running a systemd unit (<code>acbc.service</code>) that launches Gunicorn with three workers, bound to a Unix domain socket under the project directory. Nginx terminates HTTPS (provisioned by [[Let's Encrypt]] via Certbot), serves the <code>static/</code> directory directly with a one-year immutable cache header, and proxies all other requests to the Gunicorn socket. The service runs as the <code>django</code> system user out of <code>/home/django/acbc</code>.<br />
<br />
== Security and authorisation ==<br />
<br />
* Sign-ups are disabled; only the bootstrapped administrator account can authenticate.<br />
* Login attempts for any e-mail other than <code>ADMIN_EMAIL</code> are rejected without a database query.<br />
* The image-deletion helper refuses to remove any path that does not begin with <code>images/</code> or that, after canonicalisation, falls outside the configured upload folder, providing protection against path-traversal in stored data.<br />
* Story deletion requires either the administrator session or ownership of the row; image regeneration requires the administrator session.<br />
* The story-status JSON endpoint returns no user-identifying information beyond the public fields rendered on the story page.<br />
<br />
== See also ==<br />
<br />
* [[OpenAI]]<br />
* [[Flask (web framework)]]<br />
* [[H. P. Lovecraft]]<br />
* [[Computational creativity]]<br />
* [[Generative artificial intelligence]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Yusupov.cloud&diff=412Yusupov.cloud2026-04-23T14:42:57Z<p>Mvuijlst: /* Subdomains and projects */</p>
<hr />
<div>{{Infobox<br />
| name = yusupov.cloud<br />
| 1 url = https://yusupov.cloud<br />
| 2 type = Personal web sites<br />
| 3 owner = [[Michel Vuijlsteke]]<br />
| 4 launched = 2025<br />
| 5 current_status = Online<br />
}}<br />
<br />
'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref><br />
<br />
== Overview ==<br />
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref><br />
<br />
== Subdomains and projects ==<br />
Publicly visible projects include:<br />
<br />
* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''[[A Cabinet of Brief Curiosities]]'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref><br />
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref><br />
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref><br />
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''[[Digest]]'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref><br />
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref><br />
* [https://nomos.yusupov.cloud nomos.yusupov.cloud] — ''[[Nomos]]'', a daily-generating archive of fictional Flemish administrative legislation, where real Vlaamse Codex documents are semantically shifted by GPT-5 into structurally faithful but entirely invented decrees, orders, and circulars. (Built with Wagtail 7/Django 6 per operator.)<br />
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''[[Quidlibet]]'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref><br />
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''[[Thousand Year Old Vampire]]'', with Django 5 backend and Vue 3 frontend. (Per operator.)<br />
<br />
Operator-reported (not publicly discoverable at time of writing):<br />
<br />
* skills.yusupov.cloud — a skills matrix application. (Per operator.)<br />
* resources.yusupov.cloud — a simple resource planning calendar. (Per operator.)<br />
<br />
== Technology ==<br />
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" /><br />
<br />
== Relation to the BBS ==<br />
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref><br />
<br />
== See also ==<br />
* [[Yusupov's House]] (1990s BBS)<br />
* [[Michel Vuijlsteke]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Personal websites]]<br />
[[Category:Belgian websites]]<br />
[[Category:2025 establishments in Belgium]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Nomos&diff=411Nomos2026-04-20T15:42:17Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| 01_name = Nomos<br />
| 02_url = https://nomos.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2026<br />
| 05_genre = AI-generated legal document archive<br />
| 06_language = Python<br />
| 07_framework = [[Django]] / [[Wagtail]]<br />
| 08_license = Proprietary<br />
}}<br />
<br />
'''Nomos''' is a web application hosted at <code>nomos.yusupov.cloud</code> that generates and publishes AI-created Flemish administrative legislation. Each day, the system fetches a real document from the Vlaamse Codex open-data API, performs a semantic shift on its subject matter using a large language model, and produces a structurally faithful but entirely fictional legal text — a decree, ministerial order, or circular — that reads as if it were published in the ''Belgisch Staatsblad''. The generated documents are stored in a [[Wagtail (CMS)|Wagtail]] content management system and presented through a GOV.UK-inspired Dutch-language public interface. The name ''Nomos'' derives from the [[Ancient Greek|Greek]] word νόμος, meaning "law."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Django with Wagtail as its content management framework and [[SQLite]] as its development database. Additional dependencies include the [[OpenAI]] Python client for language-model calls, [[Requests (software)|Requests]] for HTTP communication with the Vlaamse Codex API, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping title inspiration from the Belgisch Staatsblad, [[Pillow (imaging library)|Pillow]] as a Wagtail dependency, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] loaded from the jsDelivr CDN with subresource integrity hashes. All user interface text is in Dutch. The planned production deployment targets a Hetzner VPS behind [[Nginx]] with [[Gunicorn]] and [[PostgreSQL]].<br />
<br />
== Data model ==<br />
<br />
The data model uses Wagtail's page tree. A singleton <code>DecreeIndexPage</code> (limited to <code>max_count = 1</code>) serves as the parent of all generated documents. Each document is a <code>DecreePage</code> with the following fields:<br />
<br />
* ''instrument'' — one of four types: Decreet, Besluit, Omzendbrief, or Reglement.<br />
* ''full_title'' (<code>TextField</code>) — the complete title, unlimited in length. The standard Wagtail ''title'' field (255-character limit) holds a truncated copy for internal use.<br />
* ''body'' (<code>RichTextField</code>) — the full HTML text of the generated legislation.<br />
* ''publication_date'' (<code>DateField</code>) — set to the generation date.<br />
* ''status'' — either ''Geldig'' (valid) or ''Gearchiveerd'' (archived); defaults to Geldig.<br />
* ''seed_id'' (<code>IntegerField</code>, unique, nullable) — the numeric ID of the source document in the Vlaamse Codex, used for deduplication to ensure no seed is used twice.<br />
* ''seed_reference'' (<code>URLField</code>) — direct API link to the source document.<br />
* ''seed_document'' (<code>TextField</code>) — human-readable label recording the type and title of the source document.<br />
* ''generation_notes'' (<code>TextField</code>) — an LLM-generated human-readable summary describing how the generated document differs from its source.<br />
* ''revision_notes'' (<code>TextField</code>) — an LLM-generated summary of the subtle details introduced during the revision stage (see below); empty if the revision was rejected or produced no changes.<br />
<br />
Full-text search is indexed on ''full_title'' and ''body'' via Wagtail's database search backend.<br />
<br />
== Generation pipeline ==<br />
<br />
Generation is driven by the <code>generate_decree</code> management command, which invokes a multi-stage pipeline implemented in <code>nomos/services/generator.py</code>. The pipeline retries up to three times if validation fails.<br />
<br />
=== Stage 1: Structural sourcing ===<br />
<br />
The <code>pick_random_seed()</code> function in <code>nomos/services/codex.py</code> fetches up to 200 recent documents from the Vlaamse Codex open-data API (<code>codex.opendata.api.vlaanderen.be</code>). Candidates are filtered to four allowed document types:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Codex type !! Mapped instrument<br />
|-<br />
| Decreet || DECREET<br />
|-<br />
| Besluit van de Vlaamse Regering || BESLUIT<br />
|-<br />
| Ministerieel besluit || BESLUIT<br />
|-<br />
| Omzendbrief || OMZENDBRIEF<br />
|}<br />
<br />
Documents whose <code>seed_id</code> already exists in the database are excluded. The remaining candidates are grouped by type, and a weighted random selection favours types that have been used less frequently in the preceding seven days. For each recently used instrument, the selection weight is reduced by two per occurrence (minimum weight of 1). Once a seed is selected, the system fetches its full detail and chapter/section structure from the API.<br />
<br />
=== Topic inspiration ===<br />
<br />
Before generating, the pipeline scrapes the ''Belgisch Staatsblad'' website (<code>ejustice.just.fgov.be</code>) for a random document title to use as thematic inspiration. To avoid reusing the same inspiration across runs, the scraper selects a random publication date from the past 90 days rather than always fetching the current edition. Federal and national references in the scraped title are replaced with Flemish equivalents using a table of 17 substitution pairs — for example, "Federale Overheidsdienst" becomes "Vlaamse overheidsdienst," "Koninklijk besluit" becomes "Besluit van de Vlaamse Regering," and "België" becomes "Vlaanderen." If the scrape fails, generation proceeds without a topic hint.<br />
<br />
=== Stage 2: Technical mutation ===<br />
<br />
The seed document's title (''opschrift'') is sent to the OpenAI Chat Completions API (the model is configurable via the <code>OPENAI_MODEL</code> environment variable). The system prompt instructs the model to behave as an expert in Flemish legislation and to perform a semantic shift: replace the core subject with a plausible but fictional technical equivalent while preserving the exact grammatical structure and bureaucratic tone. If a topic hint was obtained from the Belgisch Staatsblad, it is included as thematic guidance.<br />
<br />
=== Stage 3: Administrative drafting ===<br />
<br />
The tilted title, the seed document's full text (up to 4,000 characters), and its structural outline are sent to a second API call. The system prompt instructs the model to act as a legislative jurist of the Flemish government and to rewrite the source document about the new subject. Strict structural parity rules are enforced:<br />
<br />
* The output must contain the exact same number of chapters (''hoofdstukken''), sections (''afdelingen''), and articles (''artikelen'') as the source.<br />
* If the source has no chapter divisions, the output must not introduce them.<br />
* The total length must be comparable to the source.<br />
* Content must be entirely original — only the form is emulated.<br />
<br />
The output is requested as clean HTML using <code>&lt;h2&gt;</code>, <code>&lt;h3&gt;</code>, <code>&lt;p&gt;</code>, <code>&lt;ol&gt;</code>, and <code>&lt;li&gt;</code> elements, without a top-level heading (which is rendered separately on the page).<br />
<br />
=== Stage 3b: Subtle revision ===<br />
<br />
After drafting, the full text is sent to an additional API call that introduces ''defamiliarisation through precision'': the model is instructed to locate 3 to 5 passages dealing with execution, control, materials, or conditions, and to make a single local detail in each slightly more specific or procedural than necessary — for example, adding an unexpectedly precise measurement, a format requirement, or a procedural substep. The changes must be strictly additive; no text may be removed or truncated. Two programmatic guards run before the revision is accepted: an identity check rejects revisions that return the text unchanged, and a length check rejects revisions where the word count drops below 95% of the original (indicating deleted content). If a revision fails either guard, it is retried once. A separate validation call (the ''revision scrub'') then checks whether the revision shifted the main subject, introduced too many or contextually inappropriate details, or deleted content. If the revision is rejected or produced no changes, the unrevised text is used.<br />
<br />
=== Stage 4: Juridical scrub ===<br />
<br />
The generated HTML is submitted to a validation call in which the model acts as a quality controller. It checks for the presence of narrative, poetic, or metaphorical language; references to fiction, imagination, or art; and humor or irony. Documents that do not read as authentic administrative texts are rejected with a reason. If all three attempts fail validation, the pipeline raises an error.<br />
<br />
=== Stage 5: Generation notes ===<br />
<br />
After successful validation, an API call generates a human-readable summary of the transformation. The model is instructed to act as an archivist and to describe in one or two plain-language sentences how the new document's subject differs from the original, without technical jargon. If the subtle revision was accepted, a second call compares the pre- and post-revision texts word by word and produces a bullet-point list of the specific passages that were changed, stored as ''revision_notes''.<br />
<br />
=== Text sanitisation ===<br />
<br />
All generated text is passed through a sanitisation function that strips Unicode control characters (C0/C1 range, excluding newlines and tabs), applies NFC normalisation, removes empty list items and orphaned list wrappers from the HTML, and cleans whitespace artifacts. This addresses a known issue where some language models occasionally emit ASCII control characters in place of Unicode punctuation.<br />
<br />
=== Persistence ===<br />
<br />
The <code>save_decree()</code> function in <code>nomos/services/storage.py</code> creates a <code>DecreePage</code> as a child of the <code>DecreeIndexPage</code>. The slug is derived from the title (truncated to 200 characters) and made unique by appending a numeric suffix if necessary. The page is published immediately via Wagtail's <code>save_revision().publish()</code> mechanism. The publication date is set to the current date and the status defaults to ''Geldig''.<br />
<br />
== Anti-sameness system ==<br />
<br />
To prevent the archive from becoming repetitive, the system employs two mechanisms:<br />
<br />
* '''Seed deduplication''': the <code>seed_id</code> field (unique integer) ensures that no Vlaamse Codex document is used as a source more than once. Before selecting a seed, the pipeline queries all existing <code>seed_id</code> values and excludes them from the candidate pool.<br />
* '''Type-weighted selection''': the <code>_get_recent_type_counts()</code> function counts how many times each instrument type has appeared in the last seven days. Types with higher recent counts receive proportionally lower selection weights, encouraging the system to alternate between decrees, orders, and circulars.<br />
<br />
== Public interface ==<br />
<br />
=== Index page ===<br />
<br />
The index page lists all published <code>DecreePage</code> children ordered by publication date (newest first). A search bar and an instrument type dropdown filter are provided. Search uses Wagtail's database search backend, querying the ''full_title'' and ''body'' fields. The type filter applies an exact match on the ''instrument'' field. Each list entry displays the full title, publication date, instrument type label, and a colour-coded status tag (green for ''Geldig'', grey for ''Gearchiveerd'').<br />
<br />
=== Document detail page ===<br />
<br />
Each decree page displays:<br />
<br />
* A breadcrumb navigation link back to the index page.<br />
* The full title as a top-level heading.<br />
* A GOV.UK-style summary list with key/value rows for document type, publication date, and status (rendered as a tag badge).<br />
* The full decree body rendered as rich text.<br />
<br />
=== Visual design ===<br />
<br />
The interface is very loosely inspired by the [[GOV.UK Design System]]. The base template features a dark masthead with a yellow (<code>#ffe615</code>) accent border, the site name "Nomos" as a navigation link, and a dark/light mode toggle button. The toggle uses CSS custom properties for theming and persists the user's preference in <code>localStorage</code>. In dark mode, the masthead shifts to <code>#1a1a1a</code>, links become lighter, and status tag colours are adjusted for contrast. A responsive layout collapses the summary list key/value pairs into a single column below 576px.<br />
<br />
== Administration ==<br />
<br />
The application uses the standard Wagtail admin interface. <code>DecreePage</code> content panels expose the instrument type, full title, body, publication date, and status. A separate "Generatie-informatie" settings panel groups the seed ID, seed reference URL, seed document description, generation notes, and revision notes — metadata that is recorded automatically during generation and is accessible to editors but not displayed on the public site.<br />
<br />
The Django admin is available for lower-level database access.<br />
<br />
== Logging ==<br />
<br />
Application logging is configured with two handlers: console output and a rotating file log (<code>nomos.log</code> in the project root). The <code>nomos</code> logger is set to <code>INFO</code> level and records each pipeline stage (seed selection, title tilting, drafting, validation, publication) with document identifiers and truncated titles.<br />
<br />
== Management commands ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Command !! Purpose<br />
|-<br />
| <code>generate_decree</code> || Run the full generation pipeline: fetch seed, tilt title, draft decree, apply subtle revision, validate, generate notes, and publish as a Wagtail page<br />
|-<br />
| <code>setup_index_page</code> || Create the <code>DecreeIndexPage</code> as the site root (idempotent); removes the default Wagtail welcome page if present<br />
|}<br />
<br />
== Deployment ==<br />
<br />
The planned production deployment targets <code>nomos.yusupov.cloud</code> on a Hetzner VPS running [[Nginx]] as a reverse proxy, [[Gunicorn]] as the WSGI application server, and [[PostgreSQL]] as the production database (replacing SQLite). TLS is to be provided by [[Let's Encrypt]] via Certbot. Daily generation is to be scheduled via cron calling <code>python manage.py generate_decree</code>.<br />
<br />
== See also ==<br />
<br />
* [[OpenAI]]<br />
* [[Django (web framework)]]<br />
* [[Wagtail (CMS)]]<br />
* [[Vlaamse Codex]]<br />
* [[Computational creativity]]<br />
* [[Procedural generation]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Nomos&diff=410Nomos2026-04-20T15:41:00Z<p>Mvuijlst: /* Technology stack */</p>
<hr />
<div>{{Infobox<br />
| 01_name = Nomos<br />
| 02_url = https://nomos.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2026<br />
| 05_genre = AI-generated legal document archive<br />
| 06_language = Python<br />
| 07_framework = [[Django]] 6.0 / [[Wagtail]] 7.3<br />
| 08_license = Proprietary<br />
}}<br />
<br />
'''Nomos''' is a web application hosted at <code>nomos.yusupov.cloud</code> that generates and publishes AI-created Flemish administrative legislation. Each day, the system fetches a real document from the Vlaamse Codex open-data API, performs a semantic shift on its subject matter using a large language model, and produces a structurally faithful but entirely fictional legal text — a decree, ministerial order, or circular — that reads as if it were published in the ''Belgisch Staatsblad''. The generated documents are stored in a [[Wagtail (CMS)|Wagtail]] content management system and presented through a GOV.UK-inspired Dutch-language public interface. The name ''Nomos'' derives from the [[Ancient Greek|Greek]] word νόμος, meaning "law."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Django 6.0.4 with Wagtail 7.3.1 as its content management framework and [[SQLite]] as its development database.<ref name="requirements">requirements.txt lists Django 6.0.4, wagtail 7.3.1, openai 2.32.0, requests 2.33.1, python-dotenv 1.2.2, beautifulsoup4 4.14.3, and Pillow 12.2.0.</ref> Additional dependencies include the [[OpenAI]] Python client for language-model calls, [[Requests (software)|Requests]] for HTTP communication with the Vlaamse Codex API, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping title inspiration from the Belgisch Staatsblad, [[Pillow (imaging library)|Pillow]] as a Wagtail dependency, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] 5.3.8 loaded from the jsDelivr CDN with subresource integrity hashes. All user interface text is in Dutch.<br />
<br />
== Data model ==<br />
<br />
The data model uses Wagtail's page tree. A singleton <code>DecreeIndexPage</code> (limited to <code>max_count = 1</code>) serves as the parent of all generated documents. Each document is a <code>DecreePage</code> with the following fields:<br />
<br />
* ''instrument'' — one of four types: Decreet, Besluit, Omzendbrief, or Reglement.<br />
* ''full_title'' (<code>TextField</code>) — the complete title, unlimited in length. The standard Wagtail ''title'' field (255-character limit) holds a truncated copy for internal use.<br />
* ''body'' (<code>RichTextField</code>) — the full HTML text of the generated legislation.<br />
* ''publication_date'' (<code>DateField</code>) — set to the generation date.<br />
* ''status'' — either ''Geldig'' (valid) or ''Gearchiveerd'' (archived); defaults to Geldig.<br />
* ''seed_id'' (<code>IntegerField</code>, unique, nullable) — the numeric ID of the source document in the Vlaamse Codex, used for deduplication to ensure no seed is used twice.<br />
* ''seed_reference'' (<code>URLField</code>) — direct API link to the source document.<br />
* ''seed_document'' (<code>TextField</code>) — human-readable label recording the type and title of the source document.<br />
* ''generation_notes'' (<code>TextField</code>) — an LLM-generated human-readable summary describing how the generated document differs from its source.<br />
* ''revision_notes'' (<code>TextField</code>) — an LLM-generated summary of the subtle details introduced during the revision stage (see below); empty if the revision was rejected or produced no changes.<br />
<br />
Full-text search is indexed on ''full_title'' and ''body'' via Wagtail's database search backend.<br />
<br />
== Generation pipeline ==<br />
<br />
Generation is driven by the <code>generate_decree</code> management command, which invokes a multi-stage pipeline implemented in <code>nomos/services/generator.py</code>. The pipeline retries up to three times if validation fails.<br />
<br />
=== Stage 1: Structural sourcing ===<br />
<br />
The <code>pick_random_seed()</code> function in <code>nomos/services/codex.py</code> fetches up to 200 recent documents from the Vlaamse Codex open-data API (<code>codex.opendata.api.vlaanderen.be</code>). Candidates are filtered to four allowed document types:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Codex type !! Mapped instrument<br />
|-<br />
| Decreet || DECREET<br />
|-<br />
| Besluit van de Vlaamse Regering || BESLUIT<br />
|-<br />
| Ministerieel besluit || BESLUIT<br />
|-<br />
| Omzendbrief || OMZENDBRIEF<br />
|}<br />
<br />
Documents whose <code>seed_id</code> already exists in the database are excluded. The remaining candidates are grouped by type, and a weighted random selection favours types that have been used less frequently in the preceding seven days. For each recently used instrument, the selection weight is reduced by two per occurrence (minimum weight of 1). Once a seed is selected, the system fetches its full detail and chapter/section structure from the API.<br />
<br />
=== Topic inspiration ===<br />
<br />
Before generating, the pipeline scrapes the ''Belgisch Staatsblad'' website (<code>ejustice.just.fgov.be</code>) for a random document title to use as thematic inspiration. To avoid reusing the same inspiration across runs, the scraper selects a random publication date from the past 90 days rather than always fetching the current edition. Federal and national references in the scraped title are replaced with Flemish equivalents using a table of 17 substitution pairs — for example, "Federale Overheidsdienst" becomes "Vlaamse overheidsdienst," "Koninklijk besluit" becomes "Besluit van de Vlaamse Regering," and "België" becomes "Vlaanderen." If the scrape fails, generation proceeds without a topic hint.<br />
<br />
=== Stage 2: Technical mutation ===<br />
<br />
The seed document's title (''opschrift'') is sent to the OpenAI Chat Completions API (default model: GPT-5, configurable via the <code>OPENAI_MODEL</code> environment variable). The system prompt instructs the model to behave as an expert in Flemish legislation and to perform a semantic shift: replace the core subject with a plausible but fictional technical equivalent while preserving the exact grammatical structure and bureaucratic tone. If a topic hint was obtained from the Belgisch Staatsblad, it is included as thematic guidance.<ref name="temperature">GPT-5 does not support custom temperature values. All API calls use the model's default temperature (1).</ref><br />
<br />
=== Stage 3: Administrative drafting ===<br />
<br />
The tilted title, the seed document's full text (up to 4,000 characters), and its structural outline are sent to a second API call. The system prompt instructs the model to act as a legislative jurist of the Flemish government and to rewrite the source document about the new subject. Strict structural parity rules are enforced:<br />
<br />
* The output must contain the exact same number of chapters (''hoofdstukken''), sections (''afdelingen''), and articles (''artikelen'') as the source.<br />
* If the source has no chapter divisions, the output must not introduce them.<br />
* The total length must be comparable to the source.<br />
* Content must be entirely original — only the form is emulated.<br />
<br />
The output is requested as clean HTML using <code>&lt;h2&gt;</code>, <code>&lt;h3&gt;</code>, <code>&lt;p&gt;</code>, <code>&lt;ol&gt;</code>, and <code>&lt;li&gt;</code> elements, without a top-level heading (which is rendered separately on the page).<br />
<br />
=== Stage 3b: Subtle revision ===<br />
<br />
After drafting, the full text is sent to an additional API call that introduces ''defamiliarisation through precision'': the model is instructed to locate 3 to 5 passages dealing with execution, control, materials, or conditions, and to make a single local detail in each slightly more specific or procedural than necessary — for example, adding an unexpectedly precise measurement, a format requirement, or a procedural substep. The changes must be strictly additive; no text may be removed or truncated. Two programmatic guards run before the revision is accepted: an identity check rejects revisions that return the text unchanged, and a length check rejects revisions where the word count drops below 95% of the original (indicating deleted content). If a revision fails either guard, it is retried once. A separate validation call (the ''revision scrub'') then checks whether the revision shifted the main subject, introduced too many or contextually inappropriate details, or deleted content. If the revision is rejected or produced no changes, the unrevised text is used.<br />
<br />
=== Stage 4: Juridical scrub ===<br />
<br />
The generated HTML is submitted to a validation call in which the model acts as a quality controller. It checks for the presence of narrative, poetic, or metaphorical language; references to fiction, imagination, or art; and humor or irony. Documents that do not read as authentic administrative texts are rejected with a reason. If all three attempts fail validation, the pipeline raises an error.<br />
<br />
=== Stage 5: Generation notes ===<br />
<br />
After successful validation, an API call generates a human-readable summary of the transformation. The model is instructed to act as an archivist and to describe in one or two plain-language sentences how the new document's subject differs from the original, without technical jargon. If the subtle revision was accepted, a second call compares the pre- and post-revision texts word by word and produces a bullet-point list of the specific passages that were changed, stored as ''revision_notes''.<br />
<br />
=== Text sanitisation ===<br />
<br />
All generated text is passed through a sanitisation function that strips Unicode control characters (C0/C1 range, excluding newlines and tabs), applies NFC normalisation, removes empty list items and orphaned list wrappers from the HTML, and cleans whitespace artifacts. This addresses a known issue where GPT-5 occasionally emits ASCII control characters in place of Unicode punctuation.<br />
<br />
=== Persistence ===<br />
<br />
The <code>save_decree()</code> function in <code>nomos/services/storage.py</code> creates a <code>DecreePage</code> as a child of the <code>DecreeIndexPage</code>. The slug is derived from the title (truncated to 200 characters) and made unique by appending a numeric suffix if necessary. The page is published immediately via Wagtail's <code>save_revision().publish()</code> mechanism. The publication date is set to the current date and the status defaults to ''Geldig''.<br />
<br />
== Anti-sameness system ==<br />
<br />
To prevent the archive from becoming repetitive, the system employs two mechanisms:<br />
<br />
* '''Seed deduplication''': the <code>seed_id</code> field (unique integer) ensures that no Vlaamse Codex document is used as a source more than once. Before selecting a seed, the pipeline queries all existing <code>seed_id</code> values and excludes them from the candidate pool.<br />
* '''Type-weighted selection''': the <code>_get_recent_type_counts()</code> function counts how many times each instrument type has appeared in the last seven days. Types with higher recent counts receive proportionally lower selection weights, encouraging the system to alternate between decrees, orders, and circulars.<br />
<br />
== Public interface ==<br />
<br />
=== Index page ===<br />
<br />
The index page lists all published <code>DecreePage</code> children ordered by publication date (newest first). A search bar and an instrument type dropdown filter are provided. Search uses Wagtail's database search backend, querying the ''full_title'' and ''body'' fields. The type filter applies an exact match on the ''instrument'' field. Each list entry displays the full title, publication date, instrument type label, and a colour-coded status tag (green for ''Geldig'', grey for ''Gearchiveerd'').<br />
<br />
=== Document detail page ===<br />
<br />
Each decree page displays:<br />
<br />
* A breadcrumb navigation link back to the index page.<br />
* The full title as a top-level heading.<br />
* A GOV.UK-style summary list with key/value rows for document type, publication date, and status (rendered as a tag badge).<br />
* The full decree body rendered as rich text.<br />
<br />
=== Visual design ===<br />
<br />
The interface is very loosely inspired by the [[GOV.UK Design System]]. The base template features a dark masthead with a yellow (<code>#ffe615</code>) accent border, the site name "Nomos" as a navigation link, and a dark/light mode toggle button. The toggle uses CSS custom properties for theming and persists the user's preference in <code>localStorage</code>. In dark mode, the masthead shifts to <code>#1a1a1a</code>, links become lighter, and status tag colours are adjusted for contrast. A responsive layout collapses the summary list key/value pairs into a single column below 576px.<br />
<br />
== Administration ==<br />
<br />
The application uses the standard Wagtail admin interface. <code>DecreePage</code> content panels expose the instrument type, full title, body, publication date, and status. A separate "Generatie-informatie" settings panel groups the seed ID, seed reference URL, seed document description, generation notes, and revision notes — metadata that is recorded automatically during generation and is accessible to editors but not displayed on the public site.<br />
<br />
The Django admin is available for lower-level database access.<br />
<br />
== Logging ==<br />
<br />
Application logging is configured with two handlers: console output and a rotating file log (<code>nomos.log</code> in the project root). The <code>nomos</code> logger is set to <code>INFO</code> level and records each pipeline stage (seed selection, title tilting, drafting, validation, publication) with document identifiers and truncated titles.<br />
<br />
== Management commands ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Command !! Purpose<br />
|-<br />
| <code>generate_decree</code> || Run the full generation pipeline: fetch seed, tilt title, draft decree, apply subtle revision, validate, generate notes, and publish as a Wagtail page<br />
|-<br />
| <code>setup_index_page</code> || Create the <code>DecreeIndexPage</code> as the site root (idempotent); removes the default Wagtail welcome page if present<br />
|}<br />
<br />
== Deployment ==<br />
<br />
The planned production deployment targets <code>nomos.yusupov.cloud</code> on a Hetzner VPS running [[Nginx]] as a reverse proxy, [[Gunicorn]] as the WSGI application server, and [[PostgreSQL]] as the production database (replacing SQLite). TLS is to be provided by [[Let's Encrypt]] via Certbot. Daily generation is to be scheduled via cron calling <code>python manage.py generate_decree</code>.<br />
<br />
== See also ==<br />
<br />
* [[OpenAI]]<br />
* [[Django (web framework)]]<br />
* [[Wagtail (CMS)]]<br />
* [[Vlaamse Codex]]<br />
* [[Computational creativity]]<br />
* [[Procedural generation]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Nomos&diff=409Nomos2026-04-20T15:40:05Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| 01_name = Nomos<br />
| 02_url = https://nomos.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2026<br />
| 05_genre = AI-generated legal document archive<br />
| 06_language = Python<br />
| 07_framework = [[Django]] 6.0 / [[Wagtail]] 7.3<br />
| 08_license = Proprietary<br />
}}<br />
<br />
'''Nomos''' is a web application hosted at <code>nomos.yusupov.cloud</code> that generates and publishes AI-created Flemish administrative legislation. Each day, the system fetches a real document from the Vlaamse Codex open-data API, performs a semantic shift on its subject matter using a large language model, and produces a structurally faithful but entirely fictional legal text — a decree, ministerial order, or circular — that reads as if it were published in the ''Belgisch Staatsblad''. The generated documents are stored in a [[Wagtail (CMS)|Wagtail]] content management system and presented through a GOV.UK-inspired Dutch-language public interface. The name ''Nomos'' derives from the [[Ancient Greek|Greek]] word νόμος, meaning "law."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Django 6.0.4 with Wagtail 7.3.1 as its content management framework and [[SQLite]] as its development database.<ref name="requirements">requirements.txt lists Django 6.0.4, wagtail 7.3.1, openai 2.32.0, requests 2.33.1, python-dotenv 1.2.2, beautifulsoup4 4.14.3, and Pillow 12.2.0.</ref> Additional dependencies include the [[OpenAI]] Python client for language-model calls, [[Requests (software)|Requests]] for HTTP communication with the Vlaamse Codex API, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping title inspiration from the Belgisch Staatsblad, [[Pillow (imaging library)|Pillow]] as a Wagtail dependency, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] 5.3.8 loaded from the jsDelivr CDN with subresource integrity hashes. All user interface text is in Dutch. The planned production deployment targets a Hetzner VPS behind [[Nginx]] with [[Gunicorn]] and [[PostgreSQL]].<br />
<br />
== Data model ==<br />
<br />
The data model uses Wagtail's page tree. A singleton <code>DecreeIndexPage</code> (limited to <code>max_count = 1</code>) serves as the parent of all generated documents. Each document is a <code>DecreePage</code> with the following fields:<br />
<br />
* ''instrument'' — one of four types: Decreet, Besluit, Omzendbrief, or Reglement.<br />
* ''full_title'' (<code>TextField</code>) — the complete title, unlimited in length. The standard Wagtail ''title'' field (255-character limit) holds a truncated copy for internal use.<br />
* ''body'' (<code>RichTextField</code>) — the full HTML text of the generated legislation.<br />
* ''publication_date'' (<code>DateField</code>) — set to the generation date.<br />
* ''status'' — either ''Geldig'' (valid) or ''Gearchiveerd'' (archived); defaults to Geldig.<br />
* ''seed_id'' (<code>IntegerField</code>, unique, nullable) — the numeric ID of the source document in the Vlaamse Codex, used for deduplication to ensure no seed is used twice.<br />
* ''seed_reference'' (<code>URLField</code>) — direct API link to the source document.<br />
* ''seed_document'' (<code>TextField</code>) — human-readable label recording the type and title of the source document.<br />
* ''generation_notes'' (<code>TextField</code>) — an LLM-generated human-readable summary describing how the generated document differs from its source.<br />
* ''revision_notes'' (<code>TextField</code>) — an LLM-generated summary of the subtle details introduced during the revision stage (see below); empty if the revision was rejected or produced no changes.<br />
<br />
Full-text search is indexed on ''full_title'' and ''body'' via Wagtail's database search backend.<br />
<br />
== Generation pipeline ==<br />
<br />
Generation is driven by the <code>generate_decree</code> management command, which invokes a multi-stage pipeline implemented in <code>nomos/services/generator.py</code>. The pipeline retries up to three times if validation fails.<br />
<br />
=== Stage 1: Structural sourcing ===<br />
<br />
The <code>pick_random_seed()</code> function in <code>nomos/services/codex.py</code> fetches up to 200 recent documents from the Vlaamse Codex open-data API (<code>codex.opendata.api.vlaanderen.be</code>). Candidates are filtered to four allowed document types:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Codex type !! Mapped instrument<br />
|-<br />
| Decreet || DECREET<br />
|-<br />
| Besluit van de Vlaamse Regering || BESLUIT<br />
|-<br />
| Ministerieel besluit || BESLUIT<br />
|-<br />
| Omzendbrief || OMZENDBRIEF<br />
|}<br />
<br />
Documents whose <code>seed_id</code> already exists in the database are excluded. The remaining candidates are grouped by type, and a weighted random selection favours types that have been used less frequently in the preceding seven days. For each recently used instrument, the selection weight is reduced by two per occurrence (minimum weight of 1). Once a seed is selected, the system fetches its full detail and chapter/section structure from the API.<br />
<br />
=== Topic inspiration ===<br />
<br />
Before generating, the pipeline scrapes the ''Belgisch Staatsblad'' website (<code>ejustice.just.fgov.be</code>) for a random document title to use as thematic inspiration. To avoid reusing the same inspiration across runs, the scraper selects a random publication date from the past 90 days rather than always fetching the current edition. Federal and national references in the scraped title are replaced with Flemish equivalents using a table of 17 substitution pairs — for example, "Federale Overheidsdienst" becomes "Vlaamse overheidsdienst," "Koninklijk besluit" becomes "Besluit van de Vlaamse Regering," and "België" becomes "Vlaanderen." If the scrape fails, generation proceeds without a topic hint.<br />
<br />
=== Stage 2: Technical mutation ===<br />
<br />
The seed document's title (''opschrift'') is sent to the OpenAI Chat Completions API (default model: GPT-5, configurable via the <code>OPENAI_MODEL</code> environment variable). The system prompt instructs the model to behave as an expert in Flemish legislation and to perform a semantic shift: replace the core subject with a plausible but fictional technical equivalent while preserving the exact grammatical structure and bureaucratic tone. If a topic hint was obtained from the Belgisch Staatsblad, it is included as thematic guidance.<ref name="temperature">GPT-5 does not support custom temperature values. All API calls use the model's default temperature (1).</ref><br />
<br />
=== Stage 3: Administrative drafting ===<br />
<br />
The tilted title, the seed document's full text (up to 4,000 characters), and its structural outline are sent to a second API call. The system prompt instructs the model to act as a legislative jurist of the Flemish government and to rewrite the source document about the new subject. Strict structural parity rules are enforced:<br />
<br />
* The output must contain the exact same number of chapters (''hoofdstukken''), sections (''afdelingen''), and articles (''artikelen'') as the source.<br />
* If the source has no chapter divisions, the output must not introduce them.<br />
* The total length must be comparable to the source.<br />
* Content must be entirely original — only the form is emulated.<br />
<br />
The output is requested as clean HTML using <code>&lt;h2&gt;</code>, <code>&lt;h3&gt;</code>, <code>&lt;p&gt;</code>, <code>&lt;ol&gt;</code>, and <code>&lt;li&gt;</code> elements, without a top-level heading (which is rendered separately on the page).<br />
<br />
=== Stage 3b: Subtle revision ===<br />
<br />
After drafting, the full text is sent to an additional API call that introduces ''defamiliarisation through precision'': the model is instructed to locate 3 to 5 passages dealing with execution, control, materials, or conditions, and to make a single local detail in each slightly more specific or procedural than necessary — for example, adding an unexpectedly precise measurement, a format requirement, or a procedural substep. The changes must be strictly additive; no text may be removed or truncated. Two programmatic guards run before the revision is accepted: an identity check rejects revisions that return the text unchanged, and a length check rejects revisions where the word count drops below 95% of the original (indicating deleted content). If a revision fails either guard, it is retried once. A separate validation call (the ''revision scrub'') then checks whether the revision shifted the main subject, introduced too many or contextually inappropriate details, or deleted content. If the revision is rejected or produced no changes, the unrevised text is used.<br />
<br />
=== Stage 4: Juridical scrub ===<br />
<br />
The generated HTML is submitted to a validation call in which the model acts as a quality controller. It checks for the presence of narrative, poetic, or metaphorical language; references to fiction, imagination, or art; and humor or irony. Documents that do not read as authentic administrative texts are rejected with a reason. If all three attempts fail validation, the pipeline raises an error.<br />
<br />
=== Stage 5: Generation notes ===<br />
<br />
After successful validation, an API call generates a human-readable summary of the transformation. The model is instructed to act as an archivist and to describe in one or two plain-language sentences how the new document's subject differs from the original, without technical jargon. If the subtle revision was accepted, a second call compares the pre- and post-revision texts word by word and produces a bullet-point list of the specific passages that were changed, stored as ''revision_notes''.<br />
<br />
=== Text sanitisation ===<br />
<br />
All generated text is passed through a sanitisation function that strips Unicode control characters (C0/C1 range, excluding newlines and tabs), applies NFC normalisation, removes empty list items and orphaned list wrappers from the HTML, and cleans whitespace artifacts. This addresses a known issue where GPT-5 occasionally emits ASCII control characters in place of Unicode punctuation.<br />
<br />
=== Persistence ===<br />
<br />
The <code>save_decree()</code> function in <code>nomos/services/storage.py</code> creates a <code>DecreePage</code> as a child of the <code>DecreeIndexPage</code>. The slug is derived from the title (truncated to 200 characters) and made unique by appending a numeric suffix if necessary. The page is published immediately via Wagtail's <code>save_revision().publish()</code> mechanism. The publication date is set to the current date and the status defaults to ''Geldig''.<br />
<br />
== Anti-sameness system ==<br />
<br />
To prevent the archive from becoming repetitive, the system employs two mechanisms:<br />
<br />
* '''Seed deduplication''': the <code>seed_id</code> field (unique integer) ensures that no Vlaamse Codex document is used as a source more than once. Before selecting a seed, the pipeline queries all existing <code>seed_id</code> values and excludes them from the candidate pool.<br />
* '''Type-weighted selection''': the <code>_get_recent_type_counts()</code> function counts how many times each instrument type has appeared in the last seven days. Types with higher recent counts receive proportionally lower selection weights, encouraging the system to alternate between decrees, orders, and circulars.<br />
<br />
== Public interface ==<br />
<br />
=== Index page ===<br />
<br />
The index page lists all published <code>DecreePage</code> children ordered by publication date (newest first). A search bar and an instrument type dropdown filter are provided. Search uses Wagtail's database search backend, querying the ''full_title'' and ''body'' fields. The type filter applies an exact match on the ''instrument'' field. Each list entry displays the full title, publication date, instrument type label, and a colour-coded status tag (green for ''Geldig'', grey for ''Gearchiveerd'').<br />
<br />
=== Document detail page ===<br />
<br />
Each decree page displays:<br />
<br />
* A breadcrumb navigation link back to the index page.<br />
* The full title as a top-level heading.<br />
* A GOV.UK-style summary list with key/value rows for document type, publication date, and status (rendered as a tag badge).<br />
* The full decree body rendered as rich text.<br />
<br />
=== Visual design ===<br />
<br />
The interface is very loosely inspired by the [[GOV.UK Design System]]. The base template features a dark masthead with a yellow (<code>#ffe615</code>) accent border, the site name "Nomos" as a navigation link, and a dark/light mode toggle button. The toggle uses CSS custom properties for theming and persists the user's preference in <code>localStorage</code>. In dark mode, the masthead shifts to <code>#1a1a1a</code>, links become lighter, and status tag colours are adjusted for contrast. A responsive layout collapses the summary list key/value pairs into a single column below 576px.<br />
<br />
== Administration ==<br />
<br />
The application uses the standard Wagtail admin interface. <code>DecreePage</code> content panels expose the instrument type, full title, body, publication date, and status. A separate "Generatie-informatie" settings panel groups the seed ID, seed reference URL, seed document description, generation notes, and revision notes — metadata that is recorded automatically during generation and is accessible to editors but not displayed on the public site.<br />
<br />
The Django admin is available for lower-level database access.<br />
<br />
== Logging ==<br />
<br />
Application logging is configured with two handlers: console output and a rotating file log (<code>nomos.log</code> in the project root). The <code>nomos</code> logger is set to <code>INFO</code> level and records each pipeline stage (seed selection, title tilting, drafting, validation, publication) with document identifiers and truncated titles.<br />
<br />
== Management commands ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Command !! Purpose<br />
|-<br />
| <code>generate_decree</code> || Run the full generation pipeline: fetch seed, tilt title, draft decree, apply subtle revision, validate, generate notes, and publish as a Wagtail page<br />
|-<br />
| <code>setup_index_page</code> || Create the <code>DecreeIndexPage</code> as the site root (idempotent); removes the default Wagtail welcome page if present<br />
|}<br />
<br />
== Deployment ==<br />
<br />
The planned production deployment targets <code>nomos.yusupov.cloud</code> on a Hetzner VPS running [[Nginx]] as a reverse proxy, [[Gunicorn]] as the WSGI application server, and [[PostgreSQL]] as the production database (replacing SQLite). TLS is to be provided by [[Let's Encrypt]] via Certbot. Daily generation is to be scheduled via cron calling <code>python manage.py generate_decree</code>.<br />
<br />
== See also ==<br />
<br />
* [[OpenAI]]<br />
* [[Django (web framework)]]<br />
* [[Wagtail (CMS)]]<br />
* [[Vlaamse Codex]]<br />
* [[Computational creativity]]<br />
* [[Procedural generation]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Nomos&diff=408Nomos2026-04-19T23:18:18Z<p>Mvuijlst: Created page with "{{Infobox | 01_name = Nomos | 02_url = https://nomos.yusupov.cloud | 03_developer = Michel Vuijlsteke | 04_released = 2026 | 05_genre = AI-generated legal document archive | 06_language = Python | 07_framework = Django 6.0 / Wagtail 7.3 | 08_license = Proprietary }} '''Nomos''' is a web application hosted at <code>nomos.yusupov.cloud</code> that generates and publishes AI-created Flemish administrative legislation. Each..."</p>
<hr />
<div>{{Infobox<br />
| 01_name = Nomos<br />
| 02_url = https://nomos.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2026<br />
| 05_genre = AI-generated legal document archive<br />
| 06_language = Python<br />
| 07_framework = [[Django]] 6.0 / [[Wagtail]] 7.3<br />
| 08_license = Proprietary<br />
}}<br />
<br />
'''Nomos''' is a web application hosted at <code>nomos.yusupov.cloud</code> that generates and publishes AI-created Flemish administrative legislation. Each day, the system fetches a real document from the Vlaamse Codex open-data API, performs a semantic shift on its subject matter using a large language model, and produces a structurally faithful but entirely fictional legal text — a decree, ministerial order, or circular — that reads as if it were published in the ''Belgisch Staatsblad''. The generated documents are stored in a [[Wagtail (CMS)|Wagtail]] content management system and presented through a GOV.UK-inspired Dutch-language public interface. The name ''Nomos'' derives from the [[Ancient Greek|Greek]] word νόμος, meaning "law."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Django 6.0.4 with Wagtail 7.3.1 as its content management framework and [[SQLite]] as its development database.<ref name="requirements">requirements.txt lists Django 6.0.4, wagtail 7.3.1, openai 2.32.0, requests 2.33.1, python-dotenv 1.2.2, beautifulsoup4 4.14.3, and Pillow 12.2.0.</ref> Additional dependencies include the [[OpenAI]] Python client for language-model calls, [[Requests (software)|Requests]] for HTTP communication with the Vlaamse Codex API, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping title inspiration from the Belgisch Staatsblad, [[Pillow (imaging library)|Pillow]] as a Wagtail dependency, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] 5.3.8 loaded from the jsDelivr CDN with subresource integrity hashes. All user interface text is in Dutch. The planned production deployment targets a Hetzner VPS behind [[Nginx]] with [[Gunicorn]] and [[PostgreSQL]].<br />
<br />
== Data model ==<br />
<br />
The data model uses Wagtail's page tree. A singleton <code>DecreeIndexPage</code> (limited to <code>max_count = 1</code>) serves as the parent of all generated documents. Each document is a <code>DecreePage</code> with the following fields:<br />
<br />
* ''instrument'' — one of four types: Decreet, Besluit, Omzendbrief, or Reglement.<br />
* ''full_title'' (<code>TextField</code>) — the complete title, unlimited in length. The standard Wagtail ''title'' field (255-character limit) holds a truncated copy for internal use.<br />
* ''body'' (<code>RichTextField</code>) — the full HTML text of the generated legislation.<br />
* ''publication_date'' (<code>DateField</code>) — set to the generation date.<br />
* ''status'' — either ''Geldig'' (valid) or ''Gearchiveerd'' (archived); defaults to Geldig.<br />
* ''seed_id'' (<code>IntegerField</code>, unique, nullable) — the numeric ID of the source document in the Vlaamse Codex, used for deduplication to ensure no seed is used twice.<br />
* ''seed_reference'' (<code>URLField</code>) — direct API link to the source document.<br />
* ''seed_document'' (<code>TextField</code>) — human-readable label recording the type and title of the source document.<br />
* ''generation_notes'' (<code>TextField</code>) — an LLM-generated human-readable summary describing how the generated document differs from its source.<br />
<br />
Full-text search is indexed on ''full_title'' and ''body'' via Wagtail's database search backend.<br />
<br />
== Generation pipeline ==<br />
<br />
Generation is driven by the <code>generate_decree</code> management command, which invokes a five-stage pipeline implemented in <code>nomos/services/generator.py</code>. The pipeline retries up to three times if validation fails.<br />
<br />
=== Stage 1: Structural sourcing ===<br />
<br />
The <code>pick_random_seed()</code> function in <code>nomos/services/codex.py</code> fetches up to 200 recent documents from the Vlaamse Codex open-data API (<code>codex.opendata.api.vlaanderen.be</code>). Candidates are filtered to four allowed document types:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Codex type !! Mapped instrument<br />
|-<br />
| Decreet || DECREET<br />
|-<br />
| Besluit van de Vlaamse Regering || BESLUIT<br />
|-<br />
| Ministerieel besluit || BESLUIT<br />
|-<br />
| Omzendbrief || OMZENDBRIEF<br />
|}<br />
<br />
Documents whose <code>seed_id</code> already exists in the database are excluded. The remaining candidates are grouped by type, and a weighted random selection favours types that have been used less frequently in the preceding seven days. For each recently used instrument, the selection weight is reduced by two per occurrence (minimum weight of 1). Once a seed is selected, the system fetches its full detail and chapter/section structure from the API.<br />
<br />
=== Topic inspiration ===<br />
<br />
Before generating, the pipeline scrapes the ''Belgisch Staatsblad'' website (<code>ejustice.just.fgov.be</code>) for a random document title to use as thematic inspiration. Federal and national references in the scraped title are replaced with Flemish equivalents using a table of 17 substitution pairs — for example, "Federale Overheidsdienst" becomes "Vlaamse overheidsdienst," "Koninklijk besluit" becomes "Besluit van de Vlaamse Regering," and "België" becomes "Vlaanderen." If the scrape fails, generation proceeds without a topic hint.<br />
<br />
=== Stage 2: Technical mutation ===<br />
<br />
The seed document's title (''opschrift'') is sent to the OpenAI Chat Completions API (default model: GPT-5, configurable via the <code>OPENAI_MODEL</code> environment variable). The system prompt instructs the model to behave as an expert in Flemish legislation and to perform a semantic shift: replace the core subject with a plausible but fictional technical equivalent while preserving the exact grammatical structure and bureaucratic tone. If a topic hint was obtained from the Belgisch Staatsblad, it is included as thematic guidance.<ref name="temperature">GPT-5 does not support custom temperature values. All API calls use the model's default temperature (1).</ref><br />
<br />
=== Stage 3: Administrative drafting ===<br />
<br />
The tilted title, the seed document's full text (up to 4,000 characters), and its structural outline are sent to a second API call. The system prompt instructs the model to act as a legislative jurist of the Flemish government and to rewrite the source document about the new subject. Strict structural parity rules are enforced:<br />
<br />
* The output must contain the exact same number of chapters (''hoofdstukken''), sections (''afdelingen''), and articles (''artikelen'') as the source.<br />
* If the source has no chapter divisions, the output must not introduce them.<br />
* The total length must be comparable to the source.<br />
* Content must be entirely original — only the form is emulated.<br />
<br />
The output is requested as clean HTML using <code>&lt;h2&gt;</code>, <code>&lt;h3&gt;</code>, <code>&lt;p&gt;</code>, <code>&lt;ol&gt;</code>, and <code>&lt;li&gt;</code> elements, without a top-level heading (which is rendered separately on the page).<br />
<br />
=== Stage 4: Juridical scrub ===<br />
<br />
The generated HTML is submitted to a validation call in which the model acts as a quality controller. It checks for the presence of narrative, poetic, or metaphorical language; references to fiction, imagination, or art; and humor or irony. Documents that do not read as authentic administrative texts are rejected with a reason. If all three attempts fail validation, the pipeline raises an error.<br />
<br />
=== Stage 5: Generation notes ===<br />
<br />
After successful validation, a final API call generates a human-readable summary of the transformation. The model is instructed to act as an archivist and to describe in one or two plain-language sentences how the new document's subject differs from the original, without technical jargon.<br />
<br />
=== Text sanitisation ===<br />
<br />
All generated text is passed through a sanitisation function that strips Unicode control characters (C0/C1 range, excluding newlines and tabs), applies NFC normalisation, removes empty list items and orphaned list wrappers from the HTML, and cleans whitespace artifacts. This addresses a known issue where GPT-5 occasionally emits ASCII control characters in place of Unicode punctuation.<br />
<br />
=== Persistence ===<br />
<br />
The <code>save_decree()</code> function in <code>nomos/services/storage.py</code> creates a <code>DecreePage</code> as a child of the <code>DecreeIndexPage</code>. The slug is derived from the title (truncated to 200 characters) and made unique by appending a numeric suffix if necessary. The page is published immediately via Wagtail's <code>save_revision().publish()</code> mechanism. The publication date is set to the current date and the status defaults to ''Geldig''.<br />
<br />
== Anti-sameness system ==<br />
<br />
To prevent the archive from becoming repetitive, the system employs two mechanisms:<br />
<br />
* '''Seed deduplication''': the <code>seed_id</code> field (unique integer) ensures that no Vlaamse Codex document is used as a source more than once. Before selecting a seed, the pipeline queries all existing <code>seed_id</code> values and excludes them from the candidate pool.<br />
* '''Type-weighted selection''': the <code>_get_recent_type_counts()</code> function counts how many times each instrument type has appeared in the last seven days. Types with higher recent counts receive proportionally lower selection weights, encouraging the system to alternate between decrees, orders, and circulars.<br />
<br />
== Public interface ==<br />
<br />
=== Index page ===<br />
<br />
The index page lists all published <code>DecreePage</code> children ordered by publication date (newest first). A search bar and an instrument type dropdown filter are provided. Search uses Wagtail's database search backend, querying the ''full_title'' and ''body'' fields. The type filter applies an exact match on the ''instrument'' field. Each list entry displays the full title, publication date, instrument type label, and a colour-coded status tag (green for ''Geldig'', grey for ''Gearchiveerd'').<br />
<br />
=== Document detail page ===<br />
<br />
Each decree page displays:<br />
<br />
* A breadcrumb navigation link back to the index page.<br />
* The full title as a top-level heading.<br />
* A GOV.UK-style summary list with key/value rows for document type, publication date, and status (rendered as a tag badge).<br />
* The full decree body rendered as rich text.<br />
<br />
=== Visual design ===<br />
<br />
The interface is inspired by the [[GOV.UK Design System]]. The base template features a dark masthead with a yellow (<code>#ffe615</code>) accent border, the site name "Nomos" as a navigation link, and a dark/light mode toggle button. The toggle uses CSS custom properties for theming and persists the user's preference in <code>localStorage</code>. In dark mode, the masthead shifts to <code>#1a1a1a</code>, links become lighter, and status tag colours are adjusted for contrast. A responsive layout collapses the summary list key/value pairs into a single column below 576px.<br />
<br />
== Administration ==<br />
<br />
The application uses the standard Wagtail admin interface at <code>/admin/</code>. <code>DecreePage</code> content panels expose the instrument type, full title, body, publication date, and status. A separate "Generatie-informatie" settings panel groups the seed ID, seed reference URL, seed document description, and generation notes — metadata that is recorded automatically during generation and is accessible to editors but not displayed on the public site.<br />
<br />
The Django admin is available at <code>/django-admin/</code> for lower-level database access.<br />
<br />
== Logging ==<br />
<br />
Application logging is configured with two handlers: console output and a rotating file log (<code>nomos.log</code> in the project root). The <code>nomos</code> logger is set to <code>INFO</code> level and records each pipeline stage (seed selection, title tilting, drafting, validation, publication) with document identifiers and truncated titles.<br />
<br />
== Management commands ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Command !! Purpose<br />
|-<br />
| <code>generate_decree</code> || Run the full five-stage pipeline: fetch seed, tilt title, draft decree, validate, generate notes, and publish as a Wagtail page<br />
|-<br />
| <code>setup_index_page</code> || Create the <code>DecreeIndexPage</code> as the site root (idempotent); removes the default Wagtail welcome page if present<br />
|}<br />
<br />
== Deployment ==<br />
<br />
The planned production deployment targets <code>nomos.yusupov.cloud</code> on a Hetzner VPS running [[Nginx]] as a reverse proxy, [[Gunicorn]] as the WSGI application server, and [[PostgreSQL]] as the production database (replacing SQLite). TLS is to be provided by [[Let's Encrypt]] via Certbot. Daily generation is to be scheduled via cron calling <code>python manage.py generate_decree</code>.<br />
<br />
== See also ==<br />
<br />
* [[OpenAI]]<br />
* [[Django (web framework)]]<br />
* [[Wagtail (CMS)]]<br />
* [[Vlaamse Codex]]<br />
* [[Computational creativity]]<br />
* [[Procedural generation]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Yusupov.cloud&diff=407Yusupov.cloud2026-04-19T23:18:06Z<p>Mvuijlst: /* Subdomains and projects */</p>
<hr />
<div>{{Infobox<br />
| name = yusupov.cloud<br />
| 1 url = https://yusupov.cloud<br />
| 2 type = Personal web sites<br />
| 3 owner = [[Michel Vuijlsteke]]<br />
| 4 launched = 2025<br />
| 5 current_status = Online<br />
}}<br />
<br />
'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref><br />
<br />
== Overview ==<br />
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref><br />
<br />
== Subdomains and projects ==<br />
Publicly visible projects include:<br />
<br />
* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref><br />
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref><br />
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref><br />
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''[[Digest]]'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref><br />
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref><br />
* [https://nomos.yusupov.cloud nomos.yusupov.cloud] — ''[[Nomos]]'', a daily-generating archive of fictional Flemish administrative legislation, where real Vlaamse Codex documents are semantically shifted by GPT-5 into structurally faithful but entirely invented decrees, orders, and circulars. (Built with Wagtail 7/Django 6 per operator.)<br />
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''[[Quidlibet]]'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref><br />
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''[[Thousand Year Old Vampire]]'', with Django 5 backend and Vue 3 frontend. (Per operator.)<br />
<br />
Operator-reported (not publicly discoverable at time of writing):<br />
<br />
* skills.yusupov.cloud — a skills matrix application. (Per operator.)<br />
* resources.yusupov.cloud — a simple resource planning calendar. (Per operator.)<br />
<br />
== Technology ==<br />
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" /><br />
<br />
== Relation to the BBS ==<br />
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref><br />
<br />
== See also ==<br />
* [[Yusupov's House]] (1990s BBS)<br />
* [[Michel Vuijlsteke]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Personal websites]]<br />
[[Category:Belgian websites]]<br />
[[Category:2025 establishments in Belgium]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Michel_Vuijlsteke&diff=406Michel Vuijlsteke2026-04-19T21:15:40Z<p>Mvuijlst: /* Volunteering */</p>
<hr />
<div>{{Infobox<br />
| name = Michel Vuijlsteke<br />
| image = Michel Vuijlsteke, Gentse Feesten 2025.jpg<br />
| 01 Born = 27 August 1970, Ghent, Belgium<br />
| 03 Occupation = User experience architect; writer; former BBS/Internet early adopter<br />
| 04 Active = 1970–present<br />
| 05 Employer(s) = Ghent University, [[Albania for King Zog Committee]]<br />
| 06 Website = [https://blog.zog.org/ blog.zog.org]<br />
}}<br />
<br />
'''Michel Vuijlsteke''' (born 27 August 1970) is a Belgian user experience architect, writer and former Internet early adopter. <br />
<br />
== Biography ==<br />
Vuijlsteke was born in Ghent and studied law, but did not pursue a legal career.<ref name="cv">Michel Vuijlsteke, ''CV Michel Vuijlsteke'', 2025.</ref> In 1992 he participated in the pilot program of the [[Central European University]] in Prague, an experience he later summarized as leaving “mainly culinary impressions.”<ref name="cv" /> In 2016 he obtained a cooking diploma at the [[Spermalie Hotel School]] in Ghent, formalising a long-standing interest in food.<ref name="cv" /><br />
<br />
He lives in Ghent, is married and has four children; two cats also feature prominently in the household logistics.<ref name="cv" /><br />
<br />
== Career ==<br />
Vuijlsteke co-founded [[Netpoint]] in 1995, one of the early Internet companies in Belgium, which built websites for a variety of clients.<ref name="cv" /> After Netpoint’s acquisition by [[Unit4Agresso]] and subsequent renaming to ''Amercom België'' in 2000, he served as managing director.<ref name="cv" /> <br />
<br />
He later worked at the [[College of Europe]] and joined [[Namahn]] (2006–2010), contributing to projects in information architecture for clients including SD Worx, Belgacom and KBC.<ref name="cv" /> From 2010 to 2018 he was product owner of [[Adhese]], an online advertising platform operating in the European ad-tech niche.<ref name="cv" /> <br />
<br />
Between 2018 and 2022 he returned to [[Namahn]], mainly working on user experience architecture at [[EUROCONTROL]], where he contributed to applications used in European airspace management.<ref name="cv" /><ref name="linkedin">"Michel Vuijlsteke – LinkedIn profile". Available at: https://www.linkedin.com/in/mvuijlst/</ref><br />
<br />
Vuijlsteke is currently employed at [[Ghent University]], where he heads the team responsible for user experience and interface development across university-wide web platforms. His role combines coordination of front-end development with UX design leadership.<ref name="cv" /><br />
<br />
== Volunteering ==<br />
* At [[cirQ]] he contributed to productions such as ''Datakamp'' (2017), ''Batacratie'' (2018), ''Batastunt'' (2019) and ''cirQ TV'' during the COVID lockdown. He returned to cirQ in 2025 for ''Bataknar 2.0''<ref name="cv" /><br />
* At [[Companie Cordial]] (then ''Refu Interim'') he built a volunteer-management application and is a member of the Board<ref name="cv" /><br />
* For [[Gentblogt]] he wrote articles and took photos for many years, later serving as chair of the non-profit.<ref name="cv" /><br />
* For [[Doorway Productions]] he worked as a screenwriter and script doctor.<ref name="cv" /><br />
<br />
== Online presence ==<br />
Since 2002 Vuijlsteke writes at least daily posts on blog.zog.org, mixing technology, personal notes and commentary, which he once called “a diary that got out of hand.”<ref name="about">"Over mezelf", Zog.org. Available at: https://blog.zog.org/about</ref> Beyond the blog, he operates personal and experimental websites across multiple domains, among others: [[yusupov.cloud]], [https://moosedept.org moosedept.org], [[otlet.cloud]], [https://blaffeture.net blaffeture.net], [https://tsuk.org tsuk.org], [https://genea.cloud genea.cloud], and [https://vuijlsteke.net vuijlsteke.net].<br />
<br />
== Association with the Moose Dept. ==<br />
In addition to his professional and personal writing, Vuijlsteke has been informally connected with the [[Moose Dept.]], a subdivision of the [[Albania for King Zog Committee]]. Since at least 1989 he has occasionally signed correspondence as “Grand Mufti, Moose Dept.,” a title referenced in later interviews.<ref>Barker, W., interview with M. Vuijlsteke, 1998, privately circulated typescript.</ref><ref>Anonymous interview with M. Vuijlsteke, 2007, recorded in the AKZ Oral Archive, Ghent.</ref> <br />
<br />
The relationship between these playful titles and his broader digital projects has been the subject of some scholarly commentary.<ref>Duquesne, M., ''Domestic Esoterica: Everyday Surfaces of Secret Societies'' (''Proceedings of Contemporary Folklore'', vol. 7, 2018), pp. 52–67.</ref><br />
<br />
== Languages ==<br />
Vuijlsteke speaks Dutch and French as mother tongues, English fluently, and has working knowledge of German, Italian and Spanish.<ref name="cv" /><br />
<br />
== References ==<br />
<references /></div>Mvuijlsthttps://yusupov.cloud/index.php?title=Digest&diff=405Digest2026-04-19T20:28:35Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| 01_name = Digest<br />
| 02_url = https://digest.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2025<br />
| 05_genre = AI-generated recipe application<br />
| 06_language = Python<br />
| 07_framework = [[Django]] 5.2<br />
| 08_license = Proprietary<br />
}}<br />
<br />
'''Digest''' is a web application hosted at <code>digest.yusupov.cloud</code> that generates and publishes AI-created recipes inspired by current news articles. Each day, the system fetches articles from the ''New York Times'' RSS feed, selects two at random, and uses them as creative prompts for a large language model to invent a realistic, seasonally appropriate recipe. A companion image-generation pipeline produces editorial-quality food photography for each recipe using a composition diversity system that enforces visual variety across generations. The site's tagline is "Daily recipes inspired by the news."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Django 5.2 with [[SQLite]] as its database.<ref name="requirements">requirements.txt in the project repository lists Django ≥5.2, Pillow ≥10, openai ≥1.40, python-dotenv ≥1.0, gunicorn ≥21, requests ≥2.31, beautifulsoup4 ≥4.12, and markdown ≥3.5.</ref> It is deployed behind [[Nginx]] with [[Gunicorn]] on an Ubuntu server running two synchronous workers on port 8001. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing and optimisation, the [[OpenAI]] Python client for language-model and image-generation calls, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping recipe inspiration from external sites, [[Markdown (markup language)|python-markdown]] for rendering recipe inspiration text, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] 5.3.3 with Bootstrap Icons, and typography is set in Roboto (body), Roboto Serif (headings), and Roboto Slab (accents), loaded from Google Fonts.<br />
<br />
== Data model ==<br />
<br />
=== Recipe ===<br />
<br />
The central model is <code>Recipe</code>, which stores:<br />
<br />
* ''name'', ''slug'' (auto-generated), ''intro'' (short paragraph), ''inspiration'' (120–200-word Markdown text linking to the source articles), and ''visual_description'' (a single sentence describing the plated dish for use as an image-generation prompt).<br />
* ''hero_image'' (uploaded to <code>recipes/hero/</code>), ''base_servings'' (default 4), ''prep_time_minutes'', ''cook_time_minutes'', ''is_featured'' (boolean), and automatic ''created_at'' / ''updated_at'' timestamps.<br />
* A many-to-many relationship to <code>RecipeType</code> (one of ten canonical types: Main, Salad, One-pan, Starter, Cold dish, Soup, Side dish, Dessert, Breakfast, or Snack).<br />
<br />
=== Structured ingredients ===<br />
<br />
Ingredients are organised into optional titled groups (e.g. "Dough", "Sauce") via <code>IngredientGroup</code>. Each <code>Ingredient</code> within a group has:<br />
<br />
* A foreign key to <code>IngredientName</code> (a canonical master list of deduplicated ingredient names, each with a slug and an optional foreign key to <code>IngredientCategory</code>).<br />
* A ''quantity'' (decimal), a foreign key to <code>Unit</code> (with ''name_singular'' and ''name_plural'', e.g. "cup"/"cups", "clove"/"cloves", "g"/"g"), an optional ''note'' (e.g. "finely diced", "zested then juiced"), and an ''order'' field.<br />
²<br />
<code>IngredientCategory</code> supports arbitrary hierarchy via a self-referencing parent foreign key, enabling structures such as Fruit → Citrus → Lemon.<br />
<br />
=== Instructions ===<br />
<br />
Recipe steps are stored as <code>Direction</code> rows, optionally grouped into titled <code>InstructionGroup</code> sections. Both models carry an ''order'' field for sequencing.<br />
<br />
=== Image prompt history ===<br />
<br />
Every AI image generation attempt is recorded in <code>RecipeImagePrompt</code>, which stores the full prompt text, the visual description, five composition dimension values (camera angle, framing, setting, lighting style, mood), a ''was_centered'' boolean, and a creation timestamp. This history is queried by the composition diversity system to enforce variety across successive hero images.<br />
<br />
== Recipe generation pipeline ==<br />
<br />
Recipe generation is driven by Django management commands and a service layer in <code>recipes/services/</code>.<br />
<br />
=== Inspiration sourcing ===<br />
<br />
Two management commands gather external inspiration:<br />
<br />
* <code>fetch_nyt_inspiration</code> downloads the current ''New York Times'' front page image (saved to <code>static/img/nyt/</code>) and fetches articles from the NYT homepage RSS feed. It also manages a weighted variation-rotation state file (<code>data/nyt_variation_state.json</code>) that tracks which recipe types, cooking techniques, proteins, bases, and connection styles have been used recently.<br />
* <code>fetch_recipe_inspiration</code> scrapes the ''NYT Cooking'' and ''Dagelijkse Kost'' (VRT) websites for reference recipes, extracting titles, descriptions, and ingredient lists from embedded JSON-LD <code>Recipe</code> markup. Results are written to <code>data/inspiration.json</code>.<br />
<br />
A PowerShell script (<code>scripts/schedule_inspiration_refresh.ps1</code>) automates the inspiration refresh on a three-day cycle via Windows Task Scheduler.<br />
<br />
=== Variation rotation ===<br />
<br />
To prevent repetitive output, the system maintains weighted "draw bags" for five dimensions of recipe variety:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Dimension !! Pool size !! Examples<br />
|-<br />
| Recipe type || 10 || Main (weight 7), One-pan (3), Soup (3), Salad (2), …<br />
|-<br />
| Technique || 13 || pan-searing (3), roasting (3), stir-frying (2), sous vide (2), …<br />
|-<br />
| Protein || 9 || chicken (3), beef (3), fish (2), shellfish (2), mushrooms (2), …<br />
|-<br />
| Base || 8 || rice (3), pasta (3), potatoes (3), flatbread (2), noodles (2), …<br />
|-<br />
| Connection style || 10 || geographical (10), seasonal (4), historical (3), narrative (3), …<br />
|}<br />
<br />
Each dimension uses a weighted bag: items are added with multiplicity proportional to their weight, and one is drawn per run without replacement. When the bag empties it is refilled. Immediate repeats of the same pick are avoided when alternatives exist. State is persisted to JSON between runs.<br />
<br />
=== Prompt construction ===<br />
<br />
The <code>gen_recipe_from_nyt</code> command orchestrates the full pipeline:<br />
<br />
# Two articles are selected from the RSS feed, filtered against a usage log (<code>data/inspiration_usage.json</code>) to avoid reuse.<br />
# Variation picks are drawn for recipe type, technique, protein, base, and connection style.<br />
# A structured prompt is assembled, instructing the model to act as a professional recipe developer, invent one realistic recipe that a home cook in Belgium can make using seasonally appropriate ingredients, stay within 75 minutes total time, and use the drawn picks. The prompt includes both article summaries and one extra recipe reference from the inspiration pool (with a 2:1 preference for VRT over NYT sources).<br />
# An ingredient diversity constraint is injected: the system queries the last seven recipes' ingredients and flags any non-staple ingredient that appears in three or more of them. Flagged ingredients are added to the prompt as a hard exclusion list ("MUST NOT be used in this recipe"). A curated set of approximately 40 pantry staples — salt, oil, butter, garlic, onion, flour, water, lemon, parsley, and similar basics — is exempt from this check. The constraint is self-correcting: once a previously overused ingredient drops below the threshold it is automatically unblocked.<br />
# The prompt is appended with strict JSON schema instructions specifying the output format: name, intro, inspiration, visual description, servings, times, typed ingredient groups with quantities and units, titled instruction groups, and a recipe type from the canonical list.<br />
<br />
=== Text generation ===<br />
<br />
The <code>OpenAIRecipeGenerator</code> service class sends the prompt to the OpenAI Responses API. The default model is GPT-5, configurable via environment variable. The system prompt instructs the model to behave as a seasoned chef with Michelin-starred and home-cooking experience, and enforces detailed culinary realism rules: precise quantities ("325g not 300g"), specified heat levels and sensory cues, timing ranges, prep details in ingredient notes, assertive seasoning with salt quantities, and instructions that read like a tested recipe.<ref name="system-prompt">The system prompt in <code>recipes/services/openai_recipes.py</code> specifies: "You are a seasoned chef and food editor with 20 years of Michelin-starred and home-cooking experience."</ref><br />
<br />
The API call requests JSON object output format. If the model or SDK does not support the <code>text</code> format parameter, the call falls back to unformatted output. Similarly, if the model does not support the <code>temperature</code> parameter (as is the case with GPT-5), the call automatically retries without it.<br />
<br />
=== Validation ===<br />
<br />
After generation, the recipe JSON is passed through a self-critique step: a second, cheaper API call instructs the model to review the recipe for culinary realism — checking that quantities make sense for the serving count, that cook times are realistic for the described technique, that no ingredients mentioned in the instructions are missing from the ingredient list, and that prep notes match the steps. The model returns a corrected JSON object or the original if no issues are found. If the critique call fails, the original is used unchanged.<br />
<br />
=== Inspiration rewriting ===<br />
<br />
After generation, the pipeline inspects the <code>inspiration</code> field. If it is shorter than 120 words, contains the forbidden words "article" or "news," or lacks Markdown anchor links to both source articles, a rewrite call asks the model to produce a 120–200-word vivid text weaving concrete ideas from both sources, ending with properly formatted attribution links.<br />
<br />
=== Persistence ===<br />
<br />
The <code>save_recipe_from_data</code> function maps the generated JSON to Django models within a single transaction:<br />
<br />
* Creates the <code>Recipe</code> row with all scalar fields.<br />
* Resolves recipe types against the canonical allowed list (by slug); creates missing <code>RecipeType</code> rows only for canonical names.<br />
* Creates <code>IngredientGroup</code>, <code>Ingredient</code>, <code>IngredientName</code> (get-or-create by slug), and <code>Unit</code> (get-or-create by singular name) rows.<br />
* Normalises instruction groups: merges untitled single-step groups into one, handles multiple JSON shapes (list of strings, list of dicts with <code>step</code> or <code>text</code> keys, plain text blobs), and filters artifacts shorter than three characters.<br />
* Triggers hero image generation (non-fatal by default; controlled by the <code>OPENAI_IMAGE_REQUIRED</code> setting).<br />
<br />
=== Text sanitisation ===<br />
<br />
All generated text fields are passed through a sanitisation function before database persistence. This addresses a known issue where certain language models (notably GPT-5) emit ASCII control characters in place of Unicode punctuation — for example, <code>U+0019</code> followed by a digit where an en-dash should appear, or <code>U+0019</code> followed by <code>s</code> where a right single quotation mark is intended. The sanitisation function applies pattern-based corrections for these control character sequences, normalises Unicode dashes and quotation marks to their ASCII equivalents, and strips any remaining C0 control characters. The function is applied to the recipe name, intro, inspiration, visual description, all ingredient names and notes, and all instruction steps and group titles.<br />
<br />
== Hero image generation ==<br />
<br />
Image generation is a three-layer system: a low-level OpenAI client, a composition diversity engine, and a high-level orchestrator.<br />
<br />
=== Image API client ===<br />
<br />
<code>OpenAIImageGenerator</code> calls the OpenAI image generation endpoint (model <code>gpt-image-1.5</code> by default, configurable via <code>OPENAI_IMAGE_MODEL</code>) and returns raw PNG bytes decoded from the base64 API response. The default output size is 1536×1024 (landscape), matching typical food photography framing.<ref name="image-size">The default size is set in <code>recipes/services/openai_images.py</code> and can be overridden via the <code>OPENAI_IMAGE_SIZE</code> setting.</ref><br />
<br />
=== Composition diversity ===<br />
<br />
The <code>FoodPhotoPromptGenerator</code> enforces visual variety across successive hero images by selecting compositions from the Cartesian product of five dimensions:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Dimension !! Count !! Examples<br />
|-<br />
| Camera angle || 8 || overhead flat lay, 45° oblique, eye-level, low side, macro detail, handheld documentary, three-quarter view, tilted dutch angle<br />
|-<br />
| Framing || 11 || wide with negative space, tight crop, off-center, partial out-of-frame, action/utensil-in-motion, ingredient close-up, shallow depth-of-field, symmetrical centered, diagonal composition, …<br />
|-<br />
| Setting || 11 || white studio, stainless pro kitchen, home counter, picnic/outdoor, dark restaurant table, marble surface, wooden cutting board, concrete backdrop, vintage tile, slate serving board, …<br />
|-<br />
| Lighting || 12 || hard sun, soft window, dramatic low-key, warm tungsten, backlit steam, golden hour, bounce fill, rim lighting, diffused overhead, candlelight, …<br />
|-<br />
| Mood || 12 || modern editorial, rustic farmhouse, minimalist, street-food, celebratory, cozy homestyle, vibrant colorful, moody atmospheric, fresh healthy, indulgent decadent, …<br />
|}<br />
<br />
This yields approximately 13,000 possible combinations. The selection algorithm:<br />
<br />
# Generates all combinations and shuffles them using a cryptographically secure random source (<code>secrets.SystemRandom</code>).<br />
# Filters candidates against: angle+setting pairs used in the last 30 days (banned), recent compositions within the history window (must differ in at least 3 of 5 dimensions), and a centering constraint (no centered composition if the previous image was centered).<br />
# Falls back to progressively relaxed criteria if no perfect match exists.<br />
<br />
=== Prompt construction ===<br />
<br />
The selected composition is assembled into a detailed image prompt that specifies:<br />
<br />
* The dish name and a one-sentence visual description.<br />
* A style directive requesting "high-end editorial food photography for a cookbook or food magazine," with natural imperfections — "slight char marks, a drip of sauce, steam rising, herbs slightly wilted from heat."<br />
* The five composition dimensions.<br />
* Food styling details: realistic portion sizes, contextual props (linen napkin, scattered herbs, olive oil drizzle), visible textures (crispy skin, glossy glaze, charred edges), and a natural, non-oversaturated colour palette.<br />
* Hard constraints: photorealistic only (no illustrations), no text or watermarks, no human faces or hands, and avoidance of rustic wood unless specified.<br />
<br />
=== Persistence and attachment ===<br />
<br />
Each generation creates a <code>RecipeImagePrompt</code> record storing all composition metadata. The generated PNG is attached to the recipe's <code>hero_image</code> field via Django's file storage. On-demand regeneration is available through the upload-image view, which also accepts manual image uploads (validated for JPEG, PNG, or WebP content type, maximum 20 MB, downscaled to 2048px and converted to JPEG at 85% quality).<br />
<br />
== Public interface ==<br />
<br />
=== Home page ===<br />
<br />
The home page displays a featured recipe (hero image with title, intro, and call-to-action) and a grid of the seven most recent recipes as cards with 1:1 hero images. The layout is responsive: seven columns on desktop, three on tablet, two on mobile.<br />
<br />
=== Recipe detail ===<br />
<br />
Each recipe page (<code>/r/<slug>/</code>) features:<br />
<br />
* A hero section with the image (left, 1:1 aspect ratio, rounded shadow) and title, intro, recipe type badges (linked to type pages), and time estimates (prep, cook, total) with ingredient count.<br />
* A sticky sidebar with the ingredient list, organised by groups, with a servings control (−/+ buttons and direct input). Ingredient quantities are scaled client-side using the formula <code>scaled_qty = base_qty × (servings / base_servings)</code>, with unit pluralisation logic handling irregular forms (cup/cups, clove/cloves).<br />
* Numbered instructions below, optionally grouped by titled sections.<br />
* For authenticated users: edit, delete, and regenerate-image controls, plus a collapsible display of the raw image generation prompt.<br />
<br />
The page emits [[Schema.org]] <code>Recipe</code> JSON-LD markup (name, image, prep/cook times in ISO 8601 duration format, yield, ingredient list, and <code>HowToStep</code> instructions), Open Graph meta tags, and a canonical URL.<br />
<br />
=== Browsing ===<br />
<br />
The site provides several browsing views, all with file-based caching:<br />
<br />
* ''Meals'' (<code>/types/</code>): lists recipe types with the latest example recipe for each, linking to paginated type detail pages (12 recipes per page).<br />
* ''Ingredients'' (<code>/ingredients/</code>): a master ingredient index with recipe usage counts, linking to paginated ingredient detail pages (12 recipes per page).<br />
* ''Categories'' (<code>/categories/</code>): a hierarchical ingredient category tree with subcategories and ingredient counts, linking to paginated category detail pages (24 items per page).<br />
* ''Calendar'' (<code>/year/</code>): a year-view calendar displaying all twelve months in a responsive grid. Days on which at least one recipe was published (across all years) are rendered as hyperlinks to a day detail page (<code>/year/MM/DD/</code>), which lists all recipes for that month-and-day combination regardless of year, using the same card layout and pagination as the type detail pages.<br />
* ''About'' (<code>/about/</code>): a static information page.<br />
<br />
=== Theme ===<br />
<br />
The site supports light and dark colour themes, toggled via a moon/sun icon button in the navigation bar and persisted in <code>localStorage</code>. Dark mode uses a <code>#121212</code> background, <code>#e6e6e6</code> text, and yellow (<code>rgb(255, 193, 7)</code>) accent links, with high-contrast card and list-group styling.<br />
<br />
== Administration ==<br />
<br />
The Django admin interface is customised with:<br />
<br />
* <code>RecipeAdmin</code>: list display with name, servings, times, creation date, and featured flag; search across name, intro, and inspiration; inline editing of instruction groups and directions; horizontal filter for recipe types.<br />
* <code>IngredientNameAdmin</code>: list with category and recipe count; bulk actions for assigning or removing categories, and for merging duplicate ingredient names (which transfers all ingredient references to the merge target).<br />
* <code>IngredientCategoryAdmin</code>: hierarchical display with direct and recursive ingredient counts; inline subcategory editing; a custom overview view showing category statistics; and an action for moving ingredients between subcategories.<br />
<br />
Custom admin templates provide forms for category assignment (<code>assign_category.html</code>), category overview (<code>category_overview.html</code>), ingredient merging (<code>merge_ingredients.html</code>), and ingredient moving (<code>move_ingredients.html</code>).<br />
<br />
== SEO and caching ==<br />
<br />
Four sitemap classes are registered at <code>/sitemap.xml</code>:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Sitemap !! Items !! Priority !! Frequency<br />
|-<br />
| Recipes || All recipes || 0.9 || daily<br />
|-<br />
| Recipe types || All types || 0.6 || weekly<br />
|-<br />
| Ingredients || All ingredient names || 0.5 || weekly<br />
|-<br />
| Static pages || home, about, types index, ingredients index || 0.4 || weekly<br />
|}<br />
<br />
A <code>robots.txt</code> view allows all crawlers and includes the sitemap URL. Django's file-based cache is used throughout, with cache timeouts ranging from 5 minutes (recipe detail for anonymous users) to 1 hour (ingredient and category indexes). Cache is invalidated wholesale via <code>post_save</code>, <code>post_delete</code>, and <code>m2m_changed</code> signals on the <code>Recipe</code> model.<br />
<br />
== Deployment ==<br />
<br />
The application is deployed on an Ubuntu VPS behind Nginx, which serves static files and media directly and proxies application requests to Gunicorn on port 8001. The Gunicorn configuration specifies two synchronous workers, a 180-second request timeout (to accommodate long-running OpenAI image generation calls), and request-count-based worker recycling (1000 requests with ±100 jitter). Nginx is configured with <code>proxy_read_timeout 300s</code> for the same reason. TLS is provided by [[Let's Encrypt]] via Certbot.<br />
<br />
== Middleware ==<br />
<br />
A custom <code>ClacksOverheadMiddleware</code> adds the <code>X-Clacks-Overhead: GNU Terry Pratchett</code> header to all responses, as a tribute to [[Terry Pratchett]].<br />
<br />
== Management commands ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Command !! Purpose<br />
|-<br />
| <code>gen_recipe</code> || Generate a single recipe from a free-text topic<br />
|-<br />
| <code>gen_recipe_from_file</code> || Create a recipe from a JSON file matching the output schema<br />
|-<br />
| <code>gen_recipe_from_nyt</code> || Full pipeline: fetch NYT articles, build prompt with variation rotation, generate recipe, optionally save to database<br />
|-<br />
| <code>fix_garbled_text</code> || One-time cleanup of control-character artifacts in existing recipes<br />
|-<br />
| <code>fetch_nyt_inspiration</code> || Download NYT front page and fetch RSS articles; manage variation state<br />
|-<br />
| <code>fetch_recipe_inspiration</code> || Scrape NYT Cooking and Dagelijkse Kost for reference recipes<br />
|-<br />
| <code>create_ingredient_categories</code> || Seed the hierarchical ingredient category tree<br />
|-<br />
| <code>auto_categorize_ingredients</code> || Pattern-matching assignment of categories to uncategorised ingredients<br />
|-<br />
| <code>find_duplicate_ingredients</code> || Detect and merge duplicate ingredient names<br />
|-<br />
| <code>normalize_instructions</code> || Post-migration cleanup for instruction group schema<br />
|-<br />
| <code>seed_recipes</code> || Populate the database with sample recipes<br />
|}<br />
<br />
== See also ==<br />
<br />
* [[OpenAI]]<br />
* [[Django (web framework)]]<br />
* [[Artificial intelligence art]]<br />
* [[Computational creativity]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Digest&diff=404Digest2026-04-13T21:25:12Z<p>Mvuijlst: Created page with "{{Infobox | 01_name = Digest | 02_url = https://digest.yusupov.cloud | 03_developer = Michel Vuijlsteke | 04_released = 2025 | 05_genre = AI-generated recipe application | 06_language = Python | 07_framework = Django 5.2 | 08_license = Proprietary }} '''Digest''' is a web application hosted at <code>digest.yusupov.cloud</code> that generates and publishes AI-created recipes inspired by current news articles. Each day, the s..."</p>
<hr />
<div>{{Infobox<br />
| 01_name = Digest<br />
| 02_url = https://digest.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2025<br />
| 05_genre = AI-generated recipe application<br />
| 06_language = Python<br />
| 07_framework = [[Django]] 5.2<br />
| 08_license = Proprietary<br />
}}<br />
<br />
'''Digest''' is a web application hosted at <code>digest.yusupov.cloud</code> that generates and publishes AI-created recipes inspired by current news articles. Each day, the system fetches articles from the ''New York Times'' RSS feed, selects two at random, and uses them as creative prompts for a large language model to invent a realistic, seasonally appropriate recipe. A companion image-generation pipeline produces editorial-quality food photography for each recipe using a composition diversity system that enforces visual variety across generations. The site's tagline is "Daily recipes inspired by the news."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Django 5.2 with [[SQLite]] as its database.<ref name="requirements">requirements.txt in the project repository lists Django ≥5.2, Pillow ≥10, openai ≥1.40, python-dotenv ≥1.0, gunicorn ≥21, requests ≥2.31, beautifulsoup4 ≥4.12, and markdown ≥3.5.</ref> It is deployed behind [[Nginx]] with [[Gunicorn]] on an Ubuntu server running two synchronous workers on port 8001. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing and optimisation, the [[OpenAI]] Python client for language-model and image-generation calls, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping recipe inspiration from external sites, [[Markdown (markup language)|python-markdown]] for rendering recipe inspiration text, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] 5.3.3 with Bootstrap Icons, and typography is set in Roboto (body), Roboto Serif (headings), and Roboto Slab (accents), loaded from Google Fonts.<br />
<br />
== Data model ==<br />
<br />
=== Recipe ===<br />
<br />
The central model is <code>Recipe</code>, which stores:<br />
<br />
* ''name'', ''slug'' (auto-generated), ''intro'' (short paragraph), ''inspiration'' (120–200-word Markdown text linking to the source articles), and ''visual_description'' (a single sentence describing the plated dish for use as an image-generation prompt).<br />
* ''hero_image'' (uploaded to <code>recipes/hero/</code>), ''base_servings'' (default 4), ''prep_time_minutes'', ''cook_time_minutes'', ''is_featured'' (boolean), and automatic ''created_at'' / ''updated_at'' timestamps.<br />
* A many-to-many relationship to <code>RecipeType</code> (one of ten canonical types: Main, Salad, One-pan, Starter, Cold dish, Soup, Side dish, Dessert, Breakfast, or Snack).<br />
<br />
=== Structured ingredients ===<br />
<br />
Ingredients are organised into optional titled groups (e.g. "Dough", "Sauce") via <code>IngredientGroup</code>. Each <code>Ingredient</code> within a group has:<br />
<br />
* A foreign key to <code>IngredientName</code> (a canonical master list of deduplicated ingredient names, each with a slug and an optional foreign key to <code>IngredientCategory</code>).<br />
* A ''quantity'' (decimal), a foreign key to <code>Unit</code> (with ''name_singular'' and ''name_plural'', e.g. "cup"/"cups", "clove"/"cloves", "g"/"g"), an optional ''note'' (e.g. "finely diced", "zested then juiced"), and an ''order'' field.<br />
²<br />
<code>IngredientCategory</code> supports arbitrary hierarchy via a self-referencing parent foreign key, enabling structures such as Fruit → Citrus → Lemon.<br />
<br />
=== Instructions ===<br />
<br />
Recipe steps are stored as <code>Direction</code> rows, optionally grouped into titled <code>InstructionGroup</code> sections. Both models carry an ''order'' field for sequencing.<br />
<br />
=== Image prompt history ===<br />
<br />
Every AI image generation attempt is recorded in <code>RecipeImagePrompt</code>, which stores the full prompt text, the visual description, five composition dimension values (camera angle, framing, setting, lighting style, mood), a ''was_centered'' boolean, and a creation timestamp. This history is queried by the composition diversity system to enforce variety across successive hero images.<br />
<br />
== Recipe generation pipeline ==<br />
<br />
Recipe generation is driven by Django management commands and a service layer in <code>recipes/services/</code>.<br />
<br />
=== Inspiration sourcing ===<br />
<br />
Two management commands gather external inspiration:<br />
<br />
* <code>fetch_nyt_inspiration</code> downloads the current ''New York Times'' front page image (saved to <code>static/img/nyt/</code>) and fetches articles from the NYT homepage RSS feed. It also manages a weighted variation-rotation state file (<code>data/nyt_variation_state.json</code>) that tracks which recipe types, cooking techniques, proteins, bases, and connection styles have been used recently.<br />
* <code>fetch_recipe_inspiration</code> scrapes the ''NYT Cooking'' and ''Dagelijkse Kost'' (VRT) websites for reference recipes, extracting titles, descriptions, and ingredient lists from embedded JSON-LD <code>Recipe</code> markup. Results are written to <code>data/inspiration.json</code>.<br />
<br />
A PowerShell script (<code>scripts/schedule_inspiration_refresh.ps1</code>) automates the inspiration refresh on a three-day cycle via Windows Task Scheduler.<br />
<br />
=== Variation rotation ===<br />
<br />
To prevent repetitive output, the system maintains weighted "draw bags" for five dimensions of recipe variety:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Dimension !! Pool size !! Examples<br />
|-<br />
| Recipe type || 10 || Main (weight 7), One-pan (3), Soup (3), Salad (2), …<br />
|-<br />
| Technique || 13 || pan-searing (3), roasting (3), stir-frying (2), sous vide (2), …<br />
|-<br />
| Protein || 9 || chicken (3), beef (3), fish (2), shellfish (2), mushrooms (2), …<br />
|-<br />
| Base || 8 || rice (3), pasta (3), potatoes (3), flatbread (2), noodles (2), …<br />
|-<br />
| Connection style || 10 || geographical (10), seasonal (4), historical (3), narrative (3), …<br />
|}<br />
<br />
Each dimension uses a weighted bag: items are added with multiplicity proportional to their weight, and one is drawn per run without replacement. When the bag empties it is refilled. Immediate repeats of the same pick are avoided when alternatives exist. State is persisted to JSON between runs.<br />
<br />
=== Prompt construction ===<br />
<br />
The <code>gen_recipe_from_nyt</code> command orchestrates the full pipeline:<br />
<br />
# Two articles are selected from the RSS feed, filtered against a usage log (<code>data/inspiration_usage.json</code>) to avoid reuse.<br />
# Variation picks are drawn for recipe type, technique, protein, base, and connection style.<br />
# A structured prompt is assembled, instructing the model to act as a professional recipe developer, invent one realistic recipe that a home cook in Belgium can make using seasonally appropriate ingredients, stay within 75 minutes total time, and use the drawn picks. The prompt includes both article summaries and one extra recipe reference from the inspiration pool (with a 2:1 preference for VRT over NYT sources).<br />
# The prompt is appended with strict JSON schema instructions specifying the output format: name, intro, inspiration, visual description, servings, times, typed ingredient groups with quantities and units, titled instruction groups, and a recipe type from the canonical list.<br />
<br />
=== Text generation ===<br />
<br />
The <code>OpenAIRecipeGenerator</code> service class sends the prompt to the OpenAI Responses API. The default model is GPT-5, configurable via environment variable. The system prompt instructs the model to behave as a seasoned chef with Michelin-starred and home-cooking experience, and enforces detailed culinary realism rules: precise quantities ("325g not 300g"), specified heat levels and sensory cues, timing ranges, prep details in ingredient notes, assertive seasoning with salt quantities, and instructions that read like a tested recipe.<ref name="system-prompt">The system prompt in <code>recipes/services/openai_recipes.py</code> specifies: "You are a seasoned chef and food editor with 20 years of Michelin-starred and home-cooking experience."</ref><br />
<br />
The API call requests JSON object output format. If the model or SDK does not support the <code>text</code> format parameter, the call falls back to unformatted output. Similarly, if the model does not support the <code>temperature</code> parameter (as is the case with GPT-5), the call automatically retries without it.<br />
<br />
=== Validation ===<br />
<br />
After generation, the recipe JSON is passed through a self-critique step: a second, cheaper API call instructs the model to review the recipe for culinary realism — checking that quantities make sense for the serving count, that cook times are realistic for the described technique, that no ingredients mentioned in the instructions are missing from the ingredient list, and that prep notes match the steps. The model returns a corrected JSON object or the original if no issues are found. If the critique call fails, the original is used unchanged.<br />
<br />
=== Inspiration rewriting ===<br />
<br />
After generation, the pipeline inspects the <code>inspiration</code> field. If it is shorter than 120 words, contains the forbidden words "article" or "news," or lacks Markdown anchor links to both source articles, a rewrite call asks the model to produce a 120–200-word vivid text weaving concrete ideas from both sources, ending with properly formatted attribution links.<br />
<br />
=== Persistence ===<br />
<br />
The <code>save_recipe_from_data</code> function maps the generated JSON to Django models within a single transaction:<br />
<br />
* Creates the <code>Recipe</code> row with all scalar fields.<br />
* Resolves recipe types against the canonical allowed list (by slug); creates missing <code>RecipeType</code> rows only for canonical names.<br />
* Creates <code>IngredientGroup</code>, <code>Ingredient</code>, <code>IngredientName</code> (get-or-create by slug), and <code>Unit</code> (get-or-create by singular name) rows.<br />
* Normalises instruction groups: merges untitled single-step groups into one, handles multiple JSON shapes (list of strings, list of dicts with <code>step</code> or <code>text</code> keys, plain text blobs), and filters artifacts shorter than three characters.<br />
* Triggers hero image generation (non-fatal by default; controlled by the <code>OPENAI_IMAGE_REQUIRED</code> setting).<br />
<br />
== Hero image generation ==<br />
<br />
Image generation is a three-layer system: a low-level OpenAI client, a composition diversity engine, and a high-level orchestrator.<br />
<br />
=== Image API client ===<br />
<br />
<code>OpenAIImageGenerator</code> calls the OpenAI image generation endpoint (model <code>gpt-image-1.5</code> by default, configurable via <code>OPENAI_IMAGE_MODEL</code>) and returns raw PNG bytes decoded from the base64 API response. The default output size is 1536×1024 (landscape), matching typical food photography framing.<ref name="image-size">The default size is set in <code>recipes/services/openai_images.py</code> and can be overridden via the <code>OPENAI_IMAGE_SIZE</code> setting.</ref><br />
<br />
=== Composition diversity ===<br />
<br />
The <code>FoodPhotoPromptGenerator</code> enforces visual variety across successive hero images by selecting compositions from the Cartesian product of five dimensions:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Dimension !! Count !! Examples<br />
|-<br />
| Camera angle || 8 || overhead flat lay, 45° oblique, eye-level, low side, macro detail, handheld documentary, three-quarter view, tilted dutch angle<br />
|-<br />
| Framing || 11 || wide with negative space, tight crop, off-center, partial out-of-frame, action/utensil-in-motion, ingredient close-up, shallow depth-of-field, symmetrical centered, diagonal composition, …<br />
|-<br />
| Setting || 11 || white studio, stainless pro kitchen, home counter, picnic/outdoor, dark restaurant table, marble surface, wooden cutting board, concrete backdrop, vintage tile, slate serving board, …<br />
|-<br />
| Lighting || 12 || hard sun, soft window, dramatic low-key, warm tungsten, backlit steam, golden hour, bounce fill, rim lighting, diffused overhead, candlelight, …<br />
|-<br />
| Mood || 12 || modern editorial, rustic farmhouse, minimalist, street-food, celebratory, cozy homestyle, vibrant colorful, moody atmospheric, fresh healthy, indulgent decadent, …<br />
|}<br />
<br />
This yields approximately 13,000 possible combinations. The selection algorithm:<br />
<br />
# Generates all combinations and shuffles them using a cryptographically secure random source (<code>secrets.SystemRandom</code>).<br />
# Filters candidates against: angle+setting pairs used in the last 30 days (banned), recent compositions within the history window (must differ in at least 3 of 5 dimensions), and a centering constraint (no centered composition if the previous image was centered).<br />
# Falls back to progressively relaxed criteria if no perfect match exists.<br />
<br />
=== Prompt construction ===<br />
<br />
The selected composition is assembled into a detailed image prompt that specifies:<br />
<br />
* The dish name and a one-sentence visual description.<br />
* A style directive requesting "high-end editorial food photography for a cookbook or food magazine," with natural imperfections — "slight char marks, a drip of sauce, steam rising, herbs slightly wilted from heat."<br />
* The five composition dimensions.<br />
* Food styling details: realistic portion sizes, contextual props (linen napkin, scattered herbs, olive oil drizzle), visible textures (crispy skin, glossy glaze, charred edges), and a natural, non-oversaturated colour palette.<br />
* Hard constraints: photorealistic only (no illustrations), no text or watermarks, no human faces or hands, and avoidance of rustic wood unless specified.<br />
<br />
=== Persistence and attachment ===<br />
<br />
Each generation creates a <code>RecipeImagePrompt</code> record storing all composition metadata. The generated PNG is attached to the recipe's <code>hero_image</code> field via Django's file storage. On-demand regeneration is available through the upload-image view, which also accepts manual image uploads (validated for JPEG, PNG, or WebP content type, maximum 20 MB, downscaled to 2048px and converted to JPEG at 85% quality).<br />
<br />
== Public interface ==<br />
<br />
=== Home page ===<br />
<br />
The home page displays a featured recipe (hero image with title, intro, and call-to-action) and a grid of the seven most recent recipes as cards with 1:1 hero images. The layout is responsive: seven columns on desktop, three on tablet, two on mobile.<br />
<br />
=== Recipe detail ===<br />
<br />
Each recipe page (<code>/r/<slug>/</code>) features:<br />
<br />
* A hero section with the image (left, 1:1 aspect ratio, rounded shadow) and title, intro, recipe type badges (linked to type pages), and time estimates (prep, cook, total) with ingredient count.<br />
* A sticky sidebar with the ingredient list, organised by groups, with a servings control (−/+ buttons and direct input). Ingredient quantities are scaled client-side using the formula <code>scaled_qty = base_qty × (servings / base_servings)</code>, with unit pluralisation logic handling irregular forms (cup/cups, clove/cloves).<br />
* Numbered instructions below, optionally grouped by titled sections.<br />
* For authenticated users: edit, delete, and regenerate-image controls, plus a collapsible display of the raw image generation prompt.<br />
<br />
The page emits [[Schema.org]] <code>Recipe</code> JSON-LD markup (name, image, prep/cook times in ISO 8601 duration format, yield, ingredient list, and <code>HowToStep</code> instructions), Open Graph meta tags, and a canonical URL.<br />
<br />
=== Browsing ===<br />
<br />
The site provides several browsing views, all with file-based caching:<br />
<br />
* ''Meals'' (<code>/types/</code>): lists recipe types with the latest example recipe for each, linking to paginated type detail pages (12 recipes per page).<br />
* ''Ingredients'' (<code>/ingredients/</code>): a master ingredient index with recipe usage counts, linking to paginated ingredient detail pages (12 recipes per page).<br />
* ''Categories'' (<code>/categories/</code>): a hierarchical ingredient category tree with subcategories and ingredient counts, linking to paginated category detail pages (24 items per page).<br />
* ''About'' (<code>/about/</code>): a static information page.<br />
<br />
=== Theme ===<br />
<br />
The site supports light and dark colour themes, toggled via a moon/sun icon button in the navigation bar and persisted in <code>localStorage</code>. Dark mode uses a <code>#121212</code> background, <code>#e6e6e6</code> text, and yellow (<code>rgb(255, 193, 7)</code>) accent links, with high-contrast card and list-group styling.<br />
<br />
== Administration ==<br />
<br />
The Django admin interface is customised with:<br />
<br />
* <code>RecipeAdmin</code>: list display with name, servings, times, creation date, and featured flag; search across name, intro, and inspiration; inline editing of instruction groups and directions; horizontal filter for recipe types.<br />
* <code>IngredientNameAdmin</code>: list with category and recipe count; bulk actions for assigning or removing categories, and for merging duplicate ingredient names (which transfers all ingredient references to the merge target).<br />
* <code>IngredientCategoryAdmin</code>: hierarchical display with direct and recursive ingredient counts; inline subcategory editing; a custom overview view showing category statistics; and an action for moving ingredients between subcategories.<br />
<br />
Custom admin templates provide forms for category assignment (<code>assign_category.html</code>), category overview (<code>category_overview.html</code>), ingredient merging (<code>merge_ingredients.html</code>), and ingredient moving (<code>move_ingredients.html</code>).<br />
<br />
== SEO and caching ==<br />
<br />
Four sitemap classes are registered at <code>/sitemap.xml</code>:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Sitemap !! Items !! Priority !! Frequency<br />
|-<br />
| Recipes || All recipes || 0.9 || daily<br />
|-<br />
| Recipe types || All types || 0.6 || weekly<br />
|-<br />
| Ingredients || All ingredient names || 0.5 || weekly<br />
|-<br />
| Static pages || home, about, types index, ingredients index || 0.4 || weekly<br />
|}<br />
<br />
A <code>robots.txt</code> view allows all crawlers and includes the sitemap URL. Django's file-based cache is used throughout, with cache timeouts ranging from 5 minutes (recipe detail for anonymous users) to 1 hour (ingredient and category indexes). Cache is invalidated wholesale via <code>post_save</code>, <code>post_delete</code>, and <code>m2m_changed</code> signals on the <code>Recipe</code> model.<br />
<br />
== Deployment ==<br />
<br />
The application is deployed on an Ubuntu VPS behind Nginx, which serves static files and media directly and proxies application requests to Gunicorn on port 8001. The Gunicorn configuration specifies two synchronous workers, a 180-second request timeout (to accommodate long-running OpenAI image generation calls), and request-count-based worker recycling (1000 requests with ±100 jitter). Nginx is configured with <code>proxy_read_timeout 300s</code> for the same reason. TLS is provided by [[Let's Encrypt]] via Certbot.<br />
<br />
== Middleware ==<br />
<br />
A custom <code>ClacksOverheadMiddleware</code> adds the <code>X-Clacks-Overhead: GNU Terry Pratchett</code> header to all responses, as a tribute to [[Terry Pratchett]].<br />
<br />
== Management commands ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Command !! Purpose<br />
|-<br />
| <code>gen_recipe</code> || Generate a single recipe from a free-text topic<br />
|-<br />
| <code>gen_recipe_from_file</code> || Create a recipe from a JSON file matching the output schema<br />
|-<br />
| <code>gen_recipe_from_nyt</code> || Full pipeline: fetch NYT articles, build prompt with variation rotation, generate recipe, optionally save to database<br />
|-<br />
| <code>fetch_nyt_inspiration</code> || Download NYT front page and fetch RSS articles; manage variation state<br />
|-<br />
| <code>fetch_recipe_inspiration</code> || Scrape NYT Cooking and Dagelijkse Kost for reference recipes<br />
|-<br />
| <code>create_ingredient_categories</code> || Seed the hierarchical ingredient category tree<br />
|-<br />
| <code>auto_categorize_ingredients</code> || Pattern-matching assignment of categories to uncategorised ingredients<br />
|-<br />
| <code>find_duplicate_ingredients</code> || Detect and merge duplicate ingredient names<br />
|-<br />
| <code>normalize_instructions</code> || Post-migration cleanup for instruction group schema<br />
|-<br />
| <code>seed_recipes</code> || Populate the database with sample recipes<br />
|}<br />
<br />
== See also ==<br />
<br />
* [[OpenAI]]<br />
* [[Django (web framework)]]<br />
* [[Artificial intelligence art]]<br />
* [[Computational creativity]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Yusupov.cloud&diff=403Yusupov.cloud2026-04-13T21:25:00Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| name = yusupov.cloud<br />
| 1 url = https://yusupov.cloud<br />
| 2 type = Personal web sites<br />
| 3 owner = [[Michel Vuijlsteke]]<br />
| 4 launched = 2025<br />
| 5 current_status = Online<br />
}}<br />
<br />
'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref><br />
<br />
== Overview ==<br />
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref><br />
<br />
== Subdomains and projects ==<br />
Publicly visible projects include:<br />
<br />
* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref><br />
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref><br />
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref><br />
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''[[Digest]]'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref><br />
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref><br />
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''[[Quidlibet]]'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref><br />
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''[[Thousand Year Old Vampire]]'', with Django 5 backend and Vue 3 frontend. (Per operator.)<br />
<br />
Operator-reported (not publicly discoverable at time of writing):<br />
<br />
* skills.yusupov.cloud — a skills matrix application. (Per operator.)<br />
* resources.yusupov.cloud — a simple resource plannign calendar. (Per operator.)<br />
<br />
== Technology ==<br />
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" /><br />
<br />
== Relation to the BBS ==<br />
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref><br />
<br />
== See also ==<br />
* [[Yusupov's House]] (1990s BBS)<br />
* [[Michel Vuijlsteke]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Personal websites]]<br />
[[Category:Belgian websites]]<br />
[[Category:2025 establishments in Belgium]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Quidlibet&diff=402Quidlibet2026-04-13T13:50:01Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| 01_name = Quidlibet<br />
| 02_url = https://quidlibet.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2025<br />
| 05_genre = AI-generated fictional book library<br />
| 06_language = Python<br />
| 07_framework = [[Flask]] 3.0<br />
| 08_license = Proprietary<br />
}}<br />
<br />
'''Quidlibet''' (Latin for "anything whatsoever") is a web application hosted at <code>quidlibet.yusupov.cloud</code> that generates and catalogues entirely fictional books. Each book is a complete literary artefact: a plausible title, a named author with a biographical sketch and portrait, a Markdown-formatted synopsis, an AI-generated cover in genre-appropriate style, a publication date and page count, and between four and eight reader reviews with individually calibrated star ratings. The site presents itself as a browsable library catalogue under the heading "Possible Books," inviting visitors to enter a title and optionally an author and genre for "a book that you'd like to read but that doesn't actually exist." In addition to on-demand generation, an automated pipeline publishes up to twelve new books per day on a cron schedule.<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Flask 3.0 with Flask-SQLAlchemy as its ORM and Flask-Login for authentication.<ref name="requirements">requirements.txt in the project repository lists Flask 3.0.3, Flask-SQLAlchemy 3.1.1, Flask-Login 0.6.3, and Flask-Caching 2.3.0.</ref> It uses [[SQLite]] as its database and is deployed behind [[Nginx]] on a Linux VPS. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing, the Python <code>markdown</code> library for rich-text rendering, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for web scraping, <code>python-dotenv</code> for configuration, and the [[OpenAI]] Python client for all language-model and image-generation calls. The front end uses Bootstrap 5.3 with a custom CSS layer, Google Fonts (Roboto Serif, Roboto Slab, Roboto), and Bootstrap Icons. The site is installable as a [[progressive web application]] via a Web App Manifest and a minimal service worker.<br />
<br />
== Data model ==<br />
<br />
=== Books ===<br />
<br />
Each book record carries a ''title'', a foreign key to an ''Author'', a foreign key to a ''Genre'' (with a legacy genre-name string for backward compatibility), a Markdown ''synopsis'', a ''num_pages'' integer, an ISO 8601 ''publication_date'', a ''cover_image'' path, an ''avg_rating'' and ''rating_count'' (derived from reviews), and the ''ip_address'' and timestamp of the generation request. Books are addressed by URL slug in the form <code>/book/{id}-{title-slug}</code>, where the leading integer guarantees uniqueness and the slug provides readability.<br />
<br />
=== Authors ===<br />
<br />
Authors are stored with a ''name'' in "Lastname, Firstname" format (rendered as "Firstname Lastname" in the interface via a Jinja display-name filter), a Markdown-formatted ''bio'', and an optional ''author_image'' path. Author names are matched case-insensitively using Python's <code>SequenceMatcher</code> with a similarity threshold, so that minor variations do not create duplicate records.<br />
<br />
=== Genres ===<br />
<br />
The ''Genre'' model supports hierarchical categorisation via a self-referential ''parent_id'' foreign key. Each genre has a ''name'', an optional ''description'', a hex ''color'' code for UI tags, an ''icon'' class, a ''display_order'', and an ''is_active'' flag.<br />
<br />
=== Reviews ===<br />
<br />
Each review belongs to a book and carries a ''reviewer_name'', a ''review_date'' (in-universe), Markdown ''review_text'', and a ''stars'' rating between one and five. Reviews are cascade-deleted when their parent book is removed.<br />
<br />
=== Supporting models ===<br />
<br />
A ''GenerationJob'' tracks the asynchronous lifecycle of each generation request (pending → processing → completed or failed), with a ''progress_message'' field polled by the front end. A ''GenerationLog'' provides an audit trail of every generation attempt — successful or otherwise — including the model used, the API surface called, and any error message. A ''GenerationQueueItem'' implements a database-backed seed queue as an alternative to the file-based daily queue.<br />
<br />
== Book generation pipeline ==<br />
<br />
Book generation is performed in the main Flask application via a multi-step pipeline of OpenAI API calls. The default text model is GPT-5; the image model is <code>gpt-image-1.5</code>.<br />
<br />
=== Title and metadata ===<br />
<br />
When a visitor submits a title (and optionally an author and genre), the application creates a ''GenerationJob'' and redirects to a status page that polls for progress. On the status page, while the visitor waits, a rotating display of faux-library-science progress messages — "Reticulating splines…," "Reconciling author names against authority files…," "De-duplicating near-identical editions and printings…," "Calibrating star ratings to review sentiment…" — plays at random intervals for entertainment. Behind the scenes, the pipeline sends a structured prompt to the text model asking it to return a JSON object with the book's synopsis, page count, publication date, author name (invented if not supplied), and an author biography. The prompt instructs the model to write the synopsis in Markdown with bold and italic formatting, to keep it under two paragraphs of 120 words each, and to anchor it with concrete names, places, and objects rather than vague abstractions.<br />
<br />
=== Author reuse and continuity ===<br />
<br />
Before generating a new author, the pipeline queries the database for existing authors whose names are at least 80% similar (by sequence-matching across four name-format permutations). If a match is found — which happens for roughly a quarter of all generated books — the pipeline reuses the existing author record. It supplies the model with a context dossier listing the author's existing books, genres, and publication dates, and instructs it to revise the biography so that it naturally covers the author's expanded body of work. A hard constraint requires that any new publication date differ from the author's existing dates by at least six months. Biographies are post-processed by a helper that detects and corrects any instance of the "Lastname, Firstname" storage format that may have leaked into the prose.<br />
<br />
When the model must invent a new author, the prompt includes a dynamically generated blocklist of first and last names that already appear two or more times in the database, preventing the library from accumulating clusters of identically named authors. The blocklist is rebuilt from the live database on every generation run.<br />
<br />
=== Synopses and formatting ===<br />
<br />
Author biographies are written in Markdown: the author's name is '''bold''' on first mention and for notable awards, book titles are ''italicised'', and paragraphs are separated by blank lines. Synopses follow similar conventions. All Markdown content is rendered through a Jinja filter backed by the Python <code>markdown</code> library (with extensions for line breaks, fenced code, and tables). On grid pages where biographies appear as truncated previews, the Markdown is first rendered to HTML, then stripped of tags, so that formatting tokens do not leak into the plaintext snippet.<br />
<br />
=== Review generation and rating profiles ===<br />
<br />
Reviews are generated in a separate API call. Before prompting, the pipeline constructs a deterministic ''rating profile'' by seeding a random number generator with the SHA-256 hash of the book's title, synopsis, and publication date. This seed selects one of four rating clusters — low (18% probability, mean 2.2–3.0), mid (34%, mean 3.2–3.9), high (26%, mean 4.0–4.6), or polarised (22%, mean 3.0–3.8 with high spread) — and derives a target mean, standard deviation, skew direction, and a rant count (zero to two extended reviews of either one–two or five stars).<br />
<br />
The model is asked to produce four to eight reviews, each assigned a distinct ''stylistic palette'' from a rotating set of eight: crisp capsule (one or two punchy sentences), craft critique (prose, structure, pacing), character study (interiority, dialogue, motives), worldbuilding lens (setting, atmosphere, rules), theme tracer (motifs and subtext), comparative take (comparisons to two non-celebrity authors), sceptic's ledger (bullet-point pros and cons), and librarian angle (audience notes). Each review also rotates through a primary focus — characters, plot, prose, world, themes, or audience — so that no two reviews in a set read the same way. Review dates must fall between the book's publication date and the present day. The prompt bans stock phrases ("page-turner," "unputdownable") and requires diverse, plausible reviewer names.<br />
<br />
After creation, the pipeline calculates the book's average rating and review count directly from the database and stores them on the book record.<br />
<br />
=== Cover generation ===<br />
<br />
Cover images are generated via OpenAI's <code>gpt-image-1.5</code> model at 1024 × 1536 pixels (2:3 portrait aspect). The prompt is tailored to the book's genre through a weighted style-selection system: cookbooks receive an eightfold bias toward photographic covers; graphic novels toward vector/graphic styles; science fiction, fantasy, and horror toward illustration; biography and history toward photography; and romance toward an even mix. The prompt specifies the exact title and author name as cover typography and bans watermarks. Generated images are decoded from base64, converted to optimised progressive JPEG via Pillow (quality 92), and saved as <code>book_{id}.jpg</code>. The pipeline allows two attempts; if both fail, the entire book-generation transaction is rolled back so that no coverless book can enter the database.<br />
<br />
=== Author-photo generation ===<br />
<br />
After a successful cover, the pipeline checks whether the author already has a portrait. If not, it sends a prompt to <code>gpt-image-1.5</code> for a photorealistic head-and-shoulders portrait at 1024 × 1024 pixels. The result is centre-cropped to a 512 × 512 square JPEG and saved as <code>author_{id}.jpg</code>. Unlike cover generation, photo generation is non-blocking: failures are logged but do not abort the job. In the interface, authors without photos receive a CSS-generated avatar showing their initials.<br />
<br />
=== Error handling and transaction safety ===<br />
<br />
If any exception occurs during book creation, review insertion, or image generation, the pipeline issues an immediate <code>db.session.rollback()</code> to discard all uncommitted data. The ''GenerationJob'' and ''GenerationLog'' records — committed in an earlier transaction — survive, so the failure is auditable. The job is marked as failed with a descriptive error message. In templates, all cover <code>&lt;img&gt;</code> tags include an <code>onerror</code> handler that replaces a broken image with a CSS gradient placeholder bearing the book's title, as a defence against stale database references to missing files.<br />
<br />
== Daily batch generation ==<br />
<br />
A standalone script, <code>fast_generator.py</code>, generates twelve book seeds (title, author, genre) in a single GPT-5 API call lasting roughly twelve seconds. The batch pipeline incorporates several layers of anti-repetition machinery.<br />
<br />
=== Goodreads title inspiration ===<br />
<br />
Before prompting, the script scrapes two to three randomly chosen genre pages on [[Goodreads]] (from a pool of eight: historical fiction, history, fantasy, science fiction, romance, cookbooks, general fiction, and horror). It extracts book titles from <code>div.bookBox img[alt]</code> elements, cleans them of series numbers, author suffixes, and emoji, and presents a sample as "inspiration titles — for tone and flavour only, not to be reproduced." If Goodreads is unreachable, the script falls back to a curated JSON file of titles harvested from the [[Internet Archive]] and [[Open Library]].<br />
<br />
=== Anti-sameness system ===<br />
<br />
To prevent the model from gravitating toward a narrow band of title shapes, the script enforces structural diversity through five mechanisms:<br />
<br />
# '''Title-class rotation.''' Ten structural classes — concrete object, place or institution, named person, event or incident, documentary phrase, odd juxtaposition, fragment or question, subtitle-led, idiomatic phrase, and one-word punch — are allocated evenly across the batch so that each slot has a designated shape.<br />
# '''Avoidance guidance.''' The script analyses a rolling memory of up to 2,000 previously generated titles (persisted in a JSON file) plus all titles already in the database. It identifies the twenty most overused content words, the most common title frames (e.g., "The Last ___," "Beyond the ___"), the most frequent opening words, and the most frequent closing nouns, and encodes these as explicit "do not use" directives in the prompt.<br />
# '''Batch validator.''' After generation, each title in the batch is scored for repetitiveness: collisions on first word, end noun, or structural frame within the batch incur penalties of 0.5–1.5 points; matches against historical overuse patterns add further penalties; and two-word titles composed entirely of generic mood words score a 2.0 penalty. Titles exceeding a cumulative penalty of 3.0 are rejected and regenerated.<br />
# '''Title memory.''' Accepted titles are appended to the rolling memory file (capped at 2,000 entries, oldest dropped first) and checked against the database to prevent exact duplicates.<br />
# '''Database deduplication.''' Each final title is compared case-insensitively to every existing book in the database; duplicates are silently skipped.<br />
<br />
A parallel system applies to author names. The prompt includes a dynamically built blocklist of first and last names that already appear two or more times across the library's author table, and requires that no two authors within a single batch share a first name. The local fallback generator (used when the OpenAI API is unavailable) enforces the same within-batch uniqueness constraint on first names.<br />
<br />
The output is written to <code>daily_books.json</code>, a flat array of title/author/genre objects with generation timestamps.<br />
<br />
=== Hourly processing ===<br />
<br />
A companion script, <code>simple_hourly_processor.py</code>, runs once per hour via cron. It selects one book from the daily JSON file — indexed by a hash of the current date and hour — and triggers its full generation (metadata, reviews, cover, author photo) by calling the application's <code>/cron/hourly_book_full</code> endpoint. If all twelve daily seeds have already been processed, the hour is skipped. In production, a typical crontab runs the batch generator daily at midnight and the hourly processor every other hour, yielding up to twelve new books per day.<br />
<br />
== Cron security ==<br />
<br />
Cron endpoints are protected by a localhost check: the request's client IP must be <code>127.0.0.1</code>, <code>::1</code>, or <code>localhost</code>. For deployments where the cron job calls the public URL rather than the loopback address, two overrides are available: an <code>X-API-Key</code> header (or <code>api_key</code> query parameter) checked against an environment variable, or a global <code>DISABLE_CRON_LOCALHOST_CHECK</code> flag.<br />
<br />
== Public interface ==<br />
<br />
=== Home page ===<br />
<br />
The home page displays a hero section with the title "Possible Books," a rotating tagline (changed every thirty minutes, seeded by the current UTC half-hour), and a generation form with an autocomplete datalist of existing authors. Below the form, a grid of the twelve most recent books (with cover images or gradient fallbacks) appears alongside the twenty-five most recent reviews, sorted by review date.<br />
<br />
=== Book pages ===<br />
<br />
Each book page shows the cover image (or fallback), title, author byline linked to the author's page, genre tag, page count, publication date, and average star rating. The synopsis and author biography are rendered from Markdown. Below, reviews are listed with reviewer name, star display (filled and hollow star characters), review date, and Markdown-formatted review text. Administrators see additional controls: edit book, regenerate cover, delete book, regenerate reviews, and recalculate rating.<br />
<br />
=== Author pages ===<br />
<br />
The author page displays the portrait (or a CSS initials placeholder), the full Markdown biography, and a grid of the author's books. The authors index lists all authors sorted alphabetically by surname, with a plaintext preview of each biography (Markdown rendered, tags stripped, truncated to 100 characters).<br />
<br />
=== Archive ===<br />
<br />
The archive page presents a paginated, filterable grid of all books. A sidebar offers filters by publication-year range (dynamically bucketed), minimum average rating (one to five stars), and genre (checkboxes, grouped by popularity). Filters are applied via form auto-submission on change; an explicit "clear filters" link resets the view.<br />
<br />
=== Genres ===<br />
<br />
The genres page lists all active genres alphabetically with book counts.<br />
<br />
=== Theme ===<br />
<br />
The site defaults to a dark colour scheme (<code>#111315</code> background, <code>#e6e6e6</code> text) and supports a light mode toggled via a moon-icon button in the masthead, persisted in <code>localStorage</code>. The toggle respects the operating system's <code>prefers-color-scheme</code> setting as a default. Typography uses Roboto Serif for display headings and Roboto for body text and UI elements.<br />
<br />
== Progressive web application ==<br />
<br />
The site ships a Web App Manifest declaring standalone display mode, dark background and theme colours, and maskable icons at 192 and 512 pixels. A service worker registers at the root scope but operates in passthrough mode — all fetch events are returned unmodified — to satisfy PWA installability requirements without risking stale cached pages in a database-backed application that publishes new content hourly.<br />
<br />
== See also ==<br />
<br />
* [[Procedural generation]]<br />
* [[Flask (web framework)]]<br />
* [[OpenAI]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Quidlibet&diff=401Quidlibet2026-04-13T13:49:12Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| 01_name = Quidlibet<br />
| 02_url = https://quidlibet.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2025<br />
| 05_genre = AI-generated fictional book library<br />
| 06_language = Python<br />
| 07_framework = [[Flask]] 3.0<br />
| 08_license = Proprietary<br />
}}<br />
<br />
'''Quidlibet''' (Latin for "anything whatsoever") is a web application hosted at <code>quidlibet.yusupov.cloud</code> that generates and catalogues entirely fictional books. Each book is a complete literary artefact: a plausible title, a named author with a biographical sketch and portrait, a Markdown-formatted synopsis, an AI-generated cover in genre-appropriate style, a publication date and page count, and between four and eight reader reviews with individually calibrated star ratings. The site presents itself as a browsable library catalogue under the heading "Possible Books," inviting visitors to enter a title — and optionally an author and genre — for "a book that you'd like to read but that doesn't actually exist." In addition to on-demand generation, an automated pipeline publishes up to twelve new books per day on a cron schedule.<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Flask 3.0 with Flask-SQLAlchemy as its ORM and Flask-Login for authentication.<ref name="requirements">requirements.txt in the project repository lists Flask 3.0.3, Flask-SQLAlchemy 3.1.1, Flask-Login 0.6.3, and Flask-Caching 2.3.0.</ref> It uses [[SQLite]] as its database and is deployed behind [[Nginx]] on a Linux VPS. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing, the Python <code>markdown</code> library for rich-text rendering, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for web scraping, <code>python-dotenv</code> for configuration, and the [[OpenAI]] Python client for all language-model and image-generation calls. The front end uses Bootstrap 5.3 with a custom CSS layer, Google Fonts (Roboto Serif, Roboto Slab, Roboto), and Bootstrap Icons. The site is installable as a [[progressive web application]] via a Web App Manifest and a minimal service worker.<br />
<br />
== Data model ==<br />
<br />
=== Books ===<br />
<br />
Each book record carries a ''title'', a foreign key to an ''Author'', a foreign key to a ''Genre'' (with a legacy genre-name string for backward compatibility), a Markdown ''synopsis'', a ''num_pages'' integer, an ISO 8601 ''publication_date'', a ''cover_image'' path, an ''avg_rating'' and ''rating_count'' (derived from reviews), and the ''ip_address'' and timestamp of the generation request. Books are addressed by URL slug in the form <code>/book/{id}-{title-slug}</code>, where the leading integer guarantees uniqueness and the slug provides readability.<br />
<br />
=== Authors ===<br />
<br />
Authors are stored with a ''name'' in "Lastname, Firstname" format (rendered as "Firstname Lastname" in the interface via a Jinja display-name filter), a Markdown-formatted ''bio'', and an optional ''author_image'' path. Author names are matched case-insensitively using Python's <code>SequenceMatcher</code> with a similarity threshold, so that minor variations do not create duplicate records.<br />
<br />
=== Genres ===<br />
<br />
The ''Genre'' model supports hierarchical categorisation via a self-referential ''parent_id'' foreign key. Each genre has a ''name'', an optional ''description'', a hex ''color'' code for UI tags, an ''icon'' class, a ''display_order'', and an ''is_active'' flag.<br />
<br />
=== Reviews ===<br />
<br />
Each review belongs to a book and carries a ''reviewer_name'', a ''review_date'' (in-universe), Markdown ''review_text'', and a ''stars'' rating between one and five. Reviews are cascade-deleted when their parent book is removed.<br />
<br />
=== Supporting models ===<br />
<br />
A ''GenerationJob'' tracks the asynchronous lifecycle of each generation request (pending → processing → completed or failed), with a ''progress_message'' field polled by the front end. A ''GenerationLog'' provides an audit trail of every generation attempt — successful or otherwise — including the model used, the API surface called, and any error message. A ''GenerationQueueItem'' implements a database-backed seed queue as an alternative to the file-based daily queue.<br />
<br />
== Book generation pipeline ==<br />
<br />
Book generation is performed in the main Flask application via a multi-step pipeline of OpenAI API calls. The default text model is GPT-5; the image model is <code>gpt-image-1.5</code>.<br />
<br />
=== Title and metadata ===<br />
<br />
When a visitor submits a title (and optionally an author and genre), the application creates a ''GenerationJob'' and redirects to a status page that polls for progress. On the status page, while the visitor waits, a rotating display of faux-library-science progress messages — "Reticulating splines…," "Reconciling author names against authority files…," "De-duplicating near-identical editions and printings…," "Calibrating star ratings to review sentiment…" — plays at random intervals for entertainment. Behind the scenes, the pipeline sends a structured prompt to the text model asking it to return a JSON object with the book's synopsis, page count, publication date, author name (invented if not supplied), and an author biography. The prompt instructs the model to write the synopsis in Markdown with bold and italic formatting, to keep it under two paragraphs of 120 words each, and to anchor it with concrete names, places, and objects rather than vague abstractions.<br />
<br />
=== Author reuse and continuity ===<br />
<br />
Before generating a new author, the pipeline queries the database for existing authors whose names are at least 80% similar (by sequence-matching across four name-format permutations). If a match is found — which happens for roughly a quarter of all generated books — the pipeline reuses the existing author record. It supplies the model with a context dossier listing the author's existing books, genres, and publication dates, and instructs it to revise the biography so that it naturally covers the author's expanded body of work. A hard constraint requires that any new publication date differ from the author's existing dates by at least six months. Biographies are post-processed by a helper that detects and corrects any instance of the "Lastname, Firstname" storage format that may have leaked into the prose.<br />
<br />
When the model must invent a new author, the prompt includes a dynamically generated blocklist of first and last names that already appear two or more times in the database, preventing the library from accumulating clusters of identically named authors. The blocklist is rebuilt from the live database on every generation run.<br />
<br />
=== Synopses and formatting ===<br />
<br />
Author biographies are written in Markdown: the author's name is '''bold''' on first mention and for notable awards, book titles are ''italicised'', and paragraphs are separated by blank lines. Synopses follow similar conventions. All Markdown content is rendered through a Jinja filter backed by the Python <code>markdown</code> library (with extensions for line breaks, fenced code, and tables). On grid pages where biographies appear as truncated previews, the Markdown is first rendered to HTML, then stripped of tags, so that formatting tokens do not leak into the plaintext snippet.<br />
<br />
=== Review generation and rating profiles ===<br />
<br />
Reviews are generated in a separate API call. Before prompting, the pipeline constructs a deterministic ''rating profile'' by seeding a random number generator with the SHA-256 hash of the book's title, synopsis, and publication date. This seed selects one of four rating clusters — low (18% probability, mean 2.2–3.0), mid (34%, mean 3.2–3.9), high (26%, mean 4.0–4.6), or polarised (22%, mean 3.0–3.8 with high spread) — and derives a target mean, standard deviation, skew direction, and a rant count (zero to two extended reviews of either one–two or five stars).<br />
<br />
The model is asked to produce four to eight reviews, each assigned a distinct ''stylistic palette'' from a rotating set of eight: crisp capsule (one or two punchy sentences), craft critique (prose, structure, pacing), character study (interiority, dialogue, motives), worldbuilding lens (setting, atmosphere, rules), theme tracer (motifs and subtext), comparative take (comparisons to two non-celebrity authors), sceptic's ledger (bullet-point pros and cons), and librarian angle (audience notes). Each review also rotates through a primary focus — characters, plot, prose, world, themes, or audience — so that no two reviews in a set read the same way. Review dates must fall between the book's publication date and the present day. The prompt bans stock phrases ("page-turner," "unputdownable") and requires diverse, plausible reviewer names.<br />
<br />
After creation, the pipeline calculates the book's average rating and review count directly from the database and stores them on the book record.<br />
<br />
=== Cover generation ===<br />
<br />
Cover images are generated via OpenAI's <code>gpt-image-1.5</code> model at 1024 × 1536 pixels (2:3 portrait aspect). The prompt is tailored to the book's genre through a weighted style-selection system: cookbooks receive an eightfold bias toward photographic covers; graphic novels toward vector/graphic styles; science fiction, fantasy, and horror toward illustration; biography and history toward photography; and romance toward an even mix. The prompt specifies the exact title and author name as cover typography and bans watermarks. Generated images are decoded from base64, converted to optimised progressive JPEG via Pillow (quality 92), and saved as <code>book_{id}.jpg</code>. The pipeline allows two attempts; if both fail, the entire book-generation transaction is rolled back so that no coverless book can enter the database.<br />
<br />
=== Author-photo generation ===<br />
<br />
After a successful cover, the pipeline checks whether the author already has a portrait. If not, it sends a prompt to <code>gpt-image-1.5</code> for a photorealistic head-and-shoulders portrait at 1024 × 1024 pixels. The result is centre-cropped to a 512 × 512 square JPEG and saved as <code>author_{id}.jpg</code>. Unlike cover generation, photo generation is non-blocking: failures are logged but do not abort the job. In the interface, authors without photos receive a CSS-generated avatar showing their initials.<br />
<br />
=== Error handling and transaction safety ===<br />
<br />
If any exception occurs during book creation, review insertion, or image generation, the pipeline issues an immediate <code>db.session.rollback()</code> to discard all uncommitted data. The ''GenerationJob'' and ''GenerationLog'' records — committed in an earlier transaction — survive, so the failure is auditable. The job is marked as failed with a descriptive error message. In templates, all cover <code>&lt;img&gt;</code> tags include an <code>onerror</code> handler that replaces a broken image with a CSS gradient placeholder bearing the book's title, as a defence against stale database references to missing files.<br />
<br />
== Daily batch generation ==<br />
<br />
A standalone script, <code>fast_generator.py</code>, generates twelve book seeds (title, author, genre) in a single GPT-5 API call lasting roughly twelve seconds. The batch pipeline incorporates several layers of anti-repetition machinery.<br />
<br />
=== Goodreads title inspiration ===<br />
<br />
Before prompting, the script scrapes two to three randomly chosen genre pages on [[Goodreads]] (from a pool of eight: historical fiction, history, fantasy, science fiction, romance, cookbooks, general fiction, and horror). It extracts book titles from <code>div.bookBox img[alt]</code> elements, cleans them of series numbers, author suffixes, and emoji, and presents a sample as "inspiration titles — for tone and flavour only, not to be reproduced." If Goodreads is unreachable, the script falls back to a curated JSON file of titles harvested from the [[Internet Archive]] and [[Open Library]].<br />
<br />
=== Anti-sameness system ===<br />
<br />
To prevent the model from gravitating toward a narrow band of title shapes, the script enforces structural diversity through five mechanisms:<br />
<br />
# '''Title-class rotation.''' Ten structural classes — concrete object, place or institution, named person, event or incident, documentary phrase, odd juxtaposition, fragment or question, subtitle-led, idiomatic phrase, and one-word punch — are allocated evenly across the batch so that each slot has a designated shape.<br />
# '''Avoidance guidance.''' The script analyses a rolling memory of up to 2,000 previously generated titles (persisted in a JSON file) plus all titles already in the database. It identifies the twenty most overused content words, the most common title frames (e.g., "The Last ___," "Beyond the ___"), the most frequent opening words, and the most frequent closing nouns, and encodes these as explicit "do not use" directives in the prompt.<br />
# '''Batch validator.''' After generation, each title in the batch is scored for repetitiveness: collisions on first word, end noun, or structural frame within the batch incur penalties of 0.5–1.5 points; matches against historical overuse patterns add further penalties; and two-word titles composed entirely of generic mood words score a 2.0 penalty. Titles exceeding a cumulative penalty of 3.0 are rejected and regenerated.<br />
# '''Title memory.''' Accepted titles are appended to the rolling memory file (capped at 2,000 entries, oldest dropped first) and checked against the database to prevent exact duplicates.<br />
# '''Database deduplication.''' Each final title is compared case-insensitively to every existing book in the database; duplicates are silently skipped.<br />
<br />
A parallel system applies to author names. The prompt includes a dynamically built blocklist of first and last names that already appear two or more times across the library's author table, and requires that no two authors within a single batch share a first name. The local fallback generator (used when the OpenAI API is unavailable) enforces the same within-batch uniqueness constraint on first names.<br />
<br />
The output is written to <code>daily_books.json</code>, a flat array of title/author/genre objects with generation timestamps.<br />
<br />
=== Hourly processing ===<br />
<br />
A companion script, <code>simple_hourly_processor.py</code>, runs once per hour via cron. It selects one book from the daily JSON file — indexed by a hash of the current date and hour — and triggers its full generation (metadata, reviews, cover, author photo) by calling the application's <code>/cron/hourly_book_full</code> endpoint. If all twelve daily seeds have already been processed, the hour is skipped. In production, a typical crontab runs the batch generator daily at midnight and the hourly processor every other hour, yielding up to twelve new books per day.<br />
<br />
== Cron security ==<br />
<br />
Cron endpoints are protected by a localhost check: the request's client IP must be <code>127.0.0.1</code>, <code>::1</code>, or <code>localhost</code>. For deployments where the cron job calls the public URL rather than the loopback address, two overrides are available: an <code>X-API-Key</code> header (or <code>api_key</code> query parameter) checked against an environment variable, or a global <code>DISABLE_CRON_LOCALHOST_CHECK</code> flag.<br />
<br />
== Public interface ==<br />
<br />
=== Home page ===<br />
<br />
The home page displays a hero section with the title "Possible Books," a rotating tagline (changed every thirty minutes, seeded by the current UTC half-hour), and a generation form with an autocomplete datalist of existing authors. Below the form, a grid of the twelve most recent books (with cover images or gradient fallbacks) appears alongside the twenty-five most recent reviews, sorted by review date.<br />
<br />
=== Book pages ===<br />
<br />
Each book page shows the cover image (or fallback), title, author byline linked to the author's page, genre tag, page count, publication date, and average star rating. The synopsis and author biography are rendered from Markdown. Below, reviews are listed with reviewer name, star display (filled and hollow star characters), review date, and Markdown-formatted review text. Administrators see additional controls: edit book, regenerate cover, delete book, regenerate reviews, and recalculate rating.<br />
<br />
=== Author pages ===<br />
<br />
The author page displays the portrait (or a CSS initials placeholder), the full Markdown biography, and a grid of the author's books. The authors index lists all authors sorted alphabetically by surname, with a plaintext preview of each biography (Markdown rendered, tags stripped, truncated to 100 characters).<br />
<br />
=== Archive ===<br />
<br />
The archive page presents a paginated, filterable grid of all books. A sidebar offers filters by publication-year range (dynamically bucketed), minimum average rating (one to five stars), and genre (checkboxes, grouped by popularity). Filters are applied via form auto-submission on change; an explicit "clear filters" link resets the view.<br />
<br />
=== Genres ===<br />
<br />
The genres page lists all active genres alphabetically with book counts.<br />
<br />
=== Theme ===<br />
<br />
The site defaults to a dark colour scheme (<code>#111315</code> background, <code>#e6e6e6</code> text) and supports a light mode toggled via a moon-icon button in the masthead, persisted in <code>localStorage</code>. The toggle respects the operating system's <code>prefers-color-scheme</code> setting as a default. Typography uses Roboto Serif for display headings and Roboto for body text and UI elements.<br />
<br />
== Progressive web application ==<br />
<br />
The site ships a Web App Manifest declaring standalone display mode, dark background and theme colours, and maskable icons at 192 and 512 pixels. A service worker registers at the root scope but operates in passthrough mode — all fetch events are returned unmodified — to satisfy PWA installability requirements without risking stale cached pages in a database-backed application that publishes new content hourly.<br />
<br />
== See also ==<br />
<br />
* [[Procedural generation]]<br />
* [[Flask (web framework)]]<br />
* [[OpenAI]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Quidlibet&diff=400Quidlibet2026-04-13T13:24:04Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| 01_name = Quidlibet<br />
| 02_url = https://quidlibet.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2025<br />
| 05_genre = AI-generated fictional book library<br />
| 06_language = Python<br />
| 07_framework = [[Flask]] 3.0<br />
| 08_license = Proprietary<br />
}}<br />
<br />
'''Quidlibet''' (Latin for "anything whatsoever") is a web application hosted at <code>quidlibet.yusupov.cloud</code> that generates and catalogues entirely fictional books. Each book is a complete literary artefact: a plausible title, a named author with a biographical sketch and portrait, a Markdown-formatted synopsis, an AI-generated cover in genre-appropriate style, a publication date and page count, and between four and eight reader reviews with individually calibrated star ratings. The site presents itself as a browsable library catalogue under the heading "Possible Books," inviting visitors to enter a title and optionally an author and genre for "a book that you'd like to read but that doesn't actually exist." In addition to on-demand generation, an automated pipeline publishes up to twelve new books per day on a cron schedule.<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Flask 3.0 with Flask-SQLAlchemy as its ORM and Flask-Login for authentication.<ref name="requirements">requirements.txt in the project repository lists Flask 3.0.3, Flask-SQLAlchemy 3.1.1, Flask-Login 0.6.3, and Flask-Caching 2.3.0.</ref> It uses [[SQLite]] as its database and is deployed behind [[Nginx]] on a Linux VPS. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing, the Python <code>markdown</code> library for rich-text rendering, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for web scraping, <code>python-dotenv</code> for configuration, and the [[OpenAI]] Python client for all language-model and image-generation calls. The front end uses Bootstrap 5.3 with a custom CSS layer, Google Fonts (Roboto Serif, Roboto Slab, Roboto), and Bootstrap Icons. The site is installable as a [[progressive web application]] via a Web App Manifest and a minimal service worker.<br />
<br />
== Data model ==<br />
<br />
=== Books ===<br />
<br />
Each book record carries a ''title'', a foreign key to an ''Author'', a foreign key to a ''Genre'' (with a legacy genre-name string for backward compatibility), a Markdown ''synopsis'', a ''num_pages'' integer, an ISO 8601 ''publication_date'', a ''cover_image'' path, an ''avg_rating'' and ''rating_count'' (derived from reviews), and the ''ip_address'' and timestamp of the generation request. Books are addressed by URL slug in the form <code>/book/{id}-{title-slug}</code>, where the leading integer guarantees uniqueness and the slug provides readability.<br />
<br />
=== Authors ===<br />
<br />
Authors are stored with a ''name'' in "Lastname, Firstname" format (rendered as "Firstname Lastname" in the interface via a Jinja display-name filter), a Markdown-formatted ''bio'', and an optional ''author_image'' path. Author names are matched case-insensitively using Python's <code>SequenceMatcher</code> with a similarity threshold, so that minor variations do not create duplicate records.<br />
<br />
=== Genres ===<br />
<br />
The ''Genre'' model supports hierarchical categorisation via a self-referential ''parent_id'' foreign key. Each genre has a ''name'', an optional ''description'', a hex ''color'' code for UI tags, an ''icon'' class, a ''display_order'', and an ''is_active'' flag.<br />
<br />
=== Reviews ===<br />
<br />
Each review belongs to a book and carries a ''reviewer_name'', a ''review_date'' (in-universe), Markdown ''review_text'', and a ''stars'' rating between one and five. Reviews are cascade-deleted when their parent book is removed.<br />
<br />
=== Supporting models ===<br />
<br />
A ''GenerationJob'' tracks the asynchronous lifecycle of each generation request (pending → processing → completed or failed), with a ''progress_message'' field polled by the front end. A ''GenerationLog'' provides an audit trail of every generation attempt — successful or otherwise — including the model used, the API surface called, and any error message. A ''GenerationQueueItem'' implements a database-backed seed queue as an alternative to the file-based daily queue.<br />
<br />
== Book generation pipeline ==<br />
<br />
Book generation is performed in the main Flask application via a multi-step pipeline of OpenAI API calls. The default text model is GPT-5; the image model is <code>gpt-image-1</code>.<br />
<br />
=== Title and metadata ===<br />
<br />
When a visitor submits a title (and optionally an author and genre), the application creates a ''GenerationJob'' and redirects to a status page that polls for progress. On the status page, while the visitor waits, a rotating display of faux-library-science progress messages — "Reticulating splines…," "Reconciling author names against authority files…," "De-duplicating near-identical editions and printings…," "Calibrating star ratings to review sentiment…" — plays at random intervals for entertainment. Behind the scenes, the pipeline sends a structured prompt to the text model asking it to return a JSON object with the book's synopsis, page count, publication date, author name (invented if not supplied), and an author biography. The prompt instructs the model to write the synopsis in Markdown with bold and italic formatting, to keep it under two paragraphs of 120 words each, and to anchor it with concrete names, places, and objects rather than vague abstractions.<br />
<br />
=== Author reuse and continuity ===<br />
<br />
Before generating a new author, the pipeline queries the database for existing authors whose names are at least 80% similar (by sequence-matching across four name-format permutations). If a match is found — which happens for roughly a quarter of all generated books — the pipeline reuses the existing author record. It supplies the model with a context dossier listing the author's existing books, genres, and publication dates, and instructs it to revise the biography so that it naturally covers the author's expanded body of work. A hard constraint requires that any new publication date differ from the author's existing dates by at least six months. Biographies are post-processed by a helper that detects and corrects any instance of the "Lastname, Firstname" storage format that may have leaked into the prose.<br />
<br />
=== Synopses and formatting ===<br />
<br />
Author biographies are written in Markdown: the author's name is '''bold''' on first mention and for notable awards, book titles are ''italicised'', and paragraphs are separated by blank lines. Synopses follow similar conventions. All Markdown content is rendered through a Jinja filter backed by the Python <code>markdown</code> library (with extensions for line breaks, fenced code, and tables). On grid pages where biographies appear as truncated previews, the Markdown is first rendered to HTML, then stripped of tags, so that formatting tokens do not leak into the plaintext snippet.<br />
<br />
=== Review generation and rating profiles ===<br />
<br />
Reviews are generated in a separate API call. Before prompting, the pipeline constructs a deterministic ''rating profile'' by seeding a random number generator with the SHA-256 hash of the book's title, synopsis, and publication date. This seed selects one of four rating clusters — low (18% probability, mean 2.2–3.0), mid (34%, mean 3.2–3.9), high (26%, mean 4.0–4.6), or polarised (22%, mean 3.0–3.8 with high spread) — and derives a target mean, standard deviation, skew direction, and a rant count (zero to two extended reviews of either one–two or five stars).<br />
<br />
The model is asked to produce four to eight reviews, each assigned a distinct ''stylistic palette'' from a rotating set of eight: crisp capsule (one or two punchy sentences), craft critique (prose, structure, pacing), character study (interiority, dialogue, motives), worldbuilding lens (setting, atmosphere, rules), theme tracer (motifs and subtext), comparative take (comparisons to two non-celebrity authors), sceptic's ledger (bullet-point pros and cons), and librarian angle (audience notes). Each review also rotates through a primary focus — characters, plot, prose, world, themes, or audience — so that no two reviews in a set read the same way. Review dates must fall between the book's publication date and the present day. The prompt bans stock phrases ("page-turner," "unputdownable") and requires diverse, plausible reviewer names.<br />
<br />
After creation, the pipeline calculates the book's average rating and review count directly from the database and stores them on the book record.<br />
<br />
=== Cover generation ===<br />
<br />
Cover images are generated via OpenAI's <code>gpt-image-1</code> model at 1024 × 1536 pixels (2:3 portrait aspect). The prompt is tailored to the book's genre through a weighted style-selection system: cookbooks receive an eightfold bias toward photographic covers; graphic novels toward vector/graphic styles; science fiction, fantasy, and horror toward illustration; biography and history toward photography; and romance toward an even mix. The prompt specifies the exact title and author name as cover typography and bans watermarks. Generated images are decoded from base64, converted to optimised progressive JPEG via Pillow (quality 92), and saved as <code>book_{id}.jpg</code>. The pipeline allows two attempts; if both fail, the entire book-generation transaction is rolled back so that no coverless book can enter the database.<br />
<br />
=== Author-photo generation ===<br />
<br />
After a successful cover, the pipeline checks whether the author already has a portrait. If not, it sends a prompt to <code>gpt-image-1</code> for a photorealistic head-and-shoulders portrait at 1024 × 1024 pixels. The result is centre-cropped to a 512 × 512 square JPEG and saved as <code>author_{id}.jpg</code>. Unlike cover generation, photo generation is non-blocking: failures are logged but do not abort the job. In the interface, authors without photos receive a CSS-generated avatar showing their initials.<br />
<br />
=== Error handling and transaction safety ===<br />
<br />
If any exception occurs during book creation, review insertion, or image generation, the pipeline issues an immediate <code>db.session.rollback()</code> to discard all uncommitted data. The ''GenerationJob'' and ''GenerationLog'' records — committed in an earlier transaction — survive, so the failure is auditable. The job is marked as failed with a descriptive error message. In templates, all cover <code>&lt;img&gt;</code> tags include an <code>onerror</code> handler that replaces a broken image with a CSS gradient placeholder bearing the book's title, as a defence against stale database references to missing files.<br />
<br />
== Daily batch generation ==<br />
<br />
A standalone script, <code>fast_generator.py</code>, generates twelve book seeds (title, author, genre) in a single GPT-5 API call lasting roughly twelve seconds. The batch pipeline incorporates several layers of anti-repetition machinery.<br />
<br />
=== Goodreads title inspiration ===<br />
<br />
Before prompting, the script scrapes two to three randomly chosen genre pages on [[Goodreads]] (from a pool of eight: historical fiction, history, fantasy, science fiction, romance, cookbooks, general fiction, and horror). It extracts book titles from <code>div.bookBox img[alt]</code> elements, cleans them of series numbers, author suffixes, and emoji, and presents a sample as "inspiration titles — for tone and flavour only, not to be reproduced." If Goodreads is unreachable, the script falls back to a curated JSON file of titles harvested from the [[Internet Archive]] and [[Open Library]].<br />
<br />
=== Anti-sameness system ===<br />
<br />
To prevent the model from gravitating toward a narrow band of title shapes, the script enforces structural diversity through five mechanisms:<br />
<br />
# '''Title-class rotation.''' Ten structural classes — concrete object, place or institution, named person, event or incident, documentary phrase, odd juxtaposition, fragment or question, subtitle-led, idiomatic phrase, and one-word punch — are allocated evenly across the batch so that each slot has a designated shape.<br />
# '''Avoidance guidance.''' The script analyses a rolling memory of up to 2,000 previously generated titles (persisted in a JSON file) plus all titles already in the database. It identifies the twenty most overused content words, the most common title frames (e.g., "The Last ___," "Beyond the ___"), the most frequent opening words, and the most frequent closing nouns, and encodes these as explicit "do not use" directives in the prompt.<br />
# '''Batch validator.''' After generation, each title in the batch is scored for repetitiveness: collisions on first word, end noun, or structural frame within the batch incur penalties of 0.5–1.5 points; matches against historical overuse patterns add further penalties; and two-word titles composed entirely of generic mood words score a 2.0 penalty. Titles exceeding a cumulative penalty of 3.0 are rejected and regenerated.<br />
# '''Title memory.''' Accepted titles are appended to the rolling memory file (capped at 2,000 entries, oldest dropped first) and checked against the database to prevent exact duplicates.<br />
# '''Database deduplication.''' Each final title is compared case-insensitively to every existing book in the database; duplicates are silently skipped.<br />
<br />
The output is written to <code>daily_books.json</code>, a flat array of title/author/genre objects with generation timestamps.<br />
<br />
=== Hourly processing ===<br />
<br />
A companion script, <code>simple_hourly_processor.py</code>, runs once per hour via cron. It selects one book from the daily JSON file — indexed by a hash of the current date and hour — and triggers its full generation (metadata, reviews, cover, author photo) by calling the application's <code>/cron/hourly_book_full</code> endpoint. If all twelve daily seeds have already been processed, the hour is skipped. In production, a typical crontab runs the batch generator daily at midnight and the hourly processor every other hour, yielding up to twelve new books per day.<br />
<br />
== Cron security ==<br />
<br />
Cron endpoints are protected by a localhost check: the request's client IP must be <code>127.0.0.1</code>, <code>::1</code>, or <code>localhost</code>. For deployments where the cron job calls the public URL rather than the loopback address, two overrides are available: an <code>X-API-Key</code> header (or <code>api_key</code> query parameter) checked against an environment variable, or a global <code>DISABLE_CRON_LOCALHOST_CHECK</code> flag.<br />
<br />
== Public interface ==<br />
<br />
=== Home page ===<br />
<br />
The home page displays a hero section with the title "Possible Books," a rotating tagline (changed every thirty minutes, seeded by the current UTC half-hour), and a generation form with an autocomplete datalist of existing authors. Below the form, a grid of the twelve most recent books (with cover images or gradient fallbacks) appears alongside the twenty-five most recent reviews, sorted by review date.<br />
<br />
=== Book pages ===<br />
<br />
Each book page shows the cover image (or fallback), title, author byline linked to the author's page, genre tag, page count, publication date, and average star rating. The synopsis and author biography are rendered from Markdown. Below, reviews are listed with reviewer name, star display (filled and hollow star characters), review date, and Markdown-formatted review text. Administrators see additional controls: edit book, regenerate cover, delete book, regenerate reviews, and recalculate rating.<br />
<br />
=== Author pages ===<br />
<br />
The author page displays the portrait (or a CSS initials placeholder), the full Markdown biography, and a grid of the author's books. The authors index lists all authors sorted alphabetically by surname, with a plaintext preview of each biography (Markdown rendered, tags stripped, truncated to 100 characters).<br />
<br />
=== Archive ===<br />
<br />
The archive page presents a paginated, filterable grid of all books. A sidebar offers filters by publication-year range (dynamically bucketed), minimum average rating (one to five stars), and genre (checkboxes, grouped by popularity). Filters are applied via form auto-submission on change; an explicit "clear filters" link resets the view.<br />
<br />
=== Genres ===<br />
<br />
The genres page lists all active genres alphabetically with book counts.<br />
<br />
=== Theme ===<br />
<br />
The site defaults to a dark colour scheme (<code>#111315</code> background, <code>#e6e6e6</code> text) and supports a light mode toggled via a moon-icon button in the masthead, persisted in <code>localStorage</code>. The toggle respects the operating system's <code>prefers-color-scheme</code> setting as a default. Typography uses Roboto Serif for display headings and Roboto for body text and UI elements.<br />
<br />
== Progressive web application ==<br />
<br />
The site ships a Web App Manifest declaring standalone display mode, dark background and theme colours, and maskable icons at 192 and 512 pixels. A service worker registers at the root scope but operates in passthrough mode — all fetch events are returned unmodified — to satisfy PWA installability requirements without risking stale cached pages in a database-backed application that publishes new content hourly.<br />
<br />
== See also ==<br />
<br />
* [[Procedural generation]]<br />
* [[Flask (web framework)]]<br />
* [[OpenAI]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Quidlibet&diff=399Quidlibet2026-04-13T13:15:04Z<p>Mvuijlst: Created page with "{{Infobox | 01_name = Quidlibet | 02_url = https://quidlibet.yusupov.cloud | 03_developer = Michel Vuijlsteke | 04_released = 2025 | 05_genre = AI-generated fictional book library | 06_language = Python | 07_framework = Flask 3.0 | 08_license = Proprietary }} '''Quidlibet''' (Latin for "anything whatsoever") is a web application hosted at <code>quidlibet.yusupov.cloud</code> that generates and catalogues entirely fictional..."</p>
<hr />
<div>{{Infobox<br />
| 01_name = Quidlibet<br />
| 02_url = https://quidlibet.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2025<br />
| 05_genre = AI-generated fictional book library<br />
| 06_language = Python<br />
| 07_framework = [[Flask]] 3.0<br />
| 08_license = Proprietary<br />
}}<br />
<br />
'''Quidlibet''' (Latin for "anything whatsoever") is a web application hosted at <code>quidlibet.yusupov.cloud</code> that generates and catalogues entirely fictional books. Each book is a complete literary artefact: a plausible title, a named author with a biographical sketch and portrait, a Markdown-formatted synopsis, an AI-generated cover in genre-appropriate style, a publication date and page count, and between four and eight reader reviews with individually calibrated star ratings. The site presents itself as a browsable library catalogue under the heading "Possible Books," inviting visitors to enter a title — and optionally an author and genre — for "a book that you'd like to read but that doesn't actually exist." In addition to on-demand generation, an automated pipeline publishes up to twelve new books per day on a cron schedule.<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Flask 3.0 with Flask-SQLAlchemy as its ORM and Flask-Login for authentication.<ref name="requirements">requirements.txt in the project repository lists Flask 3.0.3, Flask-SQLAlchemy 3.1.1, Flask-Login 0.6.3, and Flask-Caching 2.3.0.</ref> It uses [[SQLite]] as its database and is deployed behind [[Nginx]] on a Linux VPS. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing, the Python <code>markdown</code> library for rich-text rendering, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for web scraping, <code>python-dotenv</code> for configuration, and the [[OpenAI]] Python client for all language-model and image-generation calls. The front end uses Bootstrap 5.3 with a custom CSS layer, Google Fonts (Roboto Serif, Roboto Slab, Roboto), and Bootstrap Icons. The site is installable as a [[progressive web application]] via a Web App Manifest and a minimal service worker.<br />
<br />
== Data model ==<br />
<br />
=== Books ===<br />
<br />
Each book record carries a ''title'', a foreign key to an ''Author'', a foreign key to a ''Genre'' (with a legacy genre-name string for backward compatibility), a Markdown ''synopsis'', a ''num_pages'' integer, an ISO 8601 ''publication_date'', a ''cover_image'' path, an ''avg_rating'' and ''rating_count'' (derived from reviews), and the ''ip_address'' and timestamp of the generation request. Books are addressed by URL slug in the form <code>/book/{id}-{title-slug}</code>, where the leading integer guarantees uniqueness and the slug provides readability.<br />
<br />
=== Authors ===<br />
<br />
Authors are stored with a ''name'' in "Lastname, Firstname" format (rendered as "Firstname Lastname" in the interface via a Jinja display-name filter), a Markdown-formatted ''bio'', and an optional ''author_image'' path. Author names are matched case-insensitively using Python's <code>SequenceMatcher</code> with a similarity threshold, so that minor variations do not create duplicate records.<br />
<br />
=== Genres ===<br />
<br />
The ''Genre'' model supports hierarchical categorisation via a self-referential ''parent_id'' foreign key. Each genre has a ''name'', an optional ''description'', a hex ''color'' code for UI tags, an ''icon'' class, a ''display_order'', and an ''is_active'' flag.<br />
<br />
=== Reviews ===<br />
<br />
Each review belongs to a book and carries a ''reviewer_name'', a ''review_date'' (in-universe), Markdown ''review_text'', and a ''stars'' rating between one and five. Reviews are cascade-deleted when their parent book is removed.<br />
<br />
=== Supporting models ===<br />
<br />
A ''GenerationJob'' tracks the asynchronous lifecycle of each generation request (pending → processing → completed or failed), with a ''progress_message'' field polled by the front end. A ''GenerationLog'' provides an audit trail of every generation attempt — successful or otherwise — including the model used, the API surface called, and any error message. A ''GenerationQueueItem'' implements a database-backed seed queue as an alternative to the file-based daily queue.<br />
<br />
== Book generation pipeline ==<br />
<br />
Book generation is performed in the main Flask application via a multi-step pipeline of OpenAI API calls. The default text model is GPT-5; the image model is <code>gpt-image-1</code>.<br />
<br />
=== Title and metadata ===<br />
<br />
When a visitor submits a title (and optionally an author and genre), the application creates a ''GenerationJob'' and redirects to a status page that polls for progress. On the status page, while the visitor waits, a rotating display of faux-library-science progress messages — "Reticulating splines…," "Reconciling author names against authority files…," "De-duplicating near-identical editions and printings…," "Calibrating star ratings to review sentiment…" — plays at random intervals for entertainment. Behind the scenes, the pipeline sends a structured prompt to the text model asking it to return a JSON object with the book's synopsis, page count, publication date, author name (invented if not supplied), and an author biography. The prompt instructs the model to write the synopsis in Markdown with bold and italic formatting, to keep it under two paragraphs of 120 words each, and to anchor it with concrete names, places, and objects rather than vague abstractions.<br />
<br />
=== Author reuse and continuity ===<br />
<br />
Before generating a new author, the pipeline queries the database for existing authors whose names are at least 80% similar (by sequence-matching across four name-format permutations). If a match is found — which happens for roughly a quarter of all generated books — the pipeline reuses the existing author record. It supplies the model with a context dossier listing the author's existing books, genres, and publication dates, and instructs it to revise the biography so that it naturally covers the author's expanded body of work. A hard constraint requires that any new publication date differ from the author's existing dates by at least six months. Biographies are post-processed by a helper that detects and corrects any instance of the "Lastname, Firstname" storage format that may have leaked into the prose.<br />
<br />
=== Synopses and formatting ===<br />
<br />
Author biographies are written in Markdown: the author's name is '''bold''' on first mention and for notable awards, book titles are ''italicised'', and paragraphs are separated by blank lines. Synopses follow similar conventions. All Markdown content is rendered through a Jinja filter backed by the Python <code>markdown</code> library (with extensions for line breaks, fenced code, and tables). On grid pages where biographies appear as truncated previews, the Markdown is first rendered to HTML, then stripped of tags, so that formatting tokens do not leak into the plaintext snippet.<br />
<br />
=== Review generation and rating profiles ===<br />
<br />
Reviews are generated in a separate API call. Before prompting, the pipeline constructs a deterministic ''rating profile'' by seeding a random number generator with the SHA-256 hash of the book's title, synopsis, and publication date. This seed selects one of four rating clusters — low (18% probability, mean 2.2–3.0), mid (34%, mean 3.2–3.9), high (26%, mean 4.0–4.6), or polarised (22%, mean 3.0–3.8 with high spread) — and derives a target mean, standard deviation, skew direction, and a rant count (zero to two extended reviews of either one–two or five stars).<br />
<br />
The model is asked to produce four to eight reviews, each assigned a distinct ''stylistic palette'' from a rotating set of eight: crisp capsule (one or two punchy sentences), craft critique (prose, structure, pacing), character study (interiority, dialogue, motives), worldbuilding lens (setting, atmosphere, rules), theme tracer (motifs and subtext), comparative take (comparisons to two non-celebrity authors), sceptic's ledger (bullet-point pros and cons), and librarian angle (audience notes). Each review also rotates through a primary focus — characters, plot, prose, world, themes, or audience — so that no two reviews in a set read the same way. Review dates must fall between the book's publication date and the present day. The prompt bans stock phrases ("page-turner," "unputdownable") and requires diverse, plausible reviewer names.<br />
<br />
After creation, the pipeline calculates the book's average rating and review count directly from the database and stores them on the book record.<br />
<br />
=== Cover generation ===<br />
<br />
Cover images are generated via OpenAI's <code>gpt-image-1</code> model at 1024 × 1536 pixels (2:3 portrait aspect). The prompt is tailored to the book's genre through a weighted style-selection system: cookbooks receive an eightfold bias toward photographic covers; graphic novels toward vector/graphic styles; science fiction, fantasy, and horror toward illustration; biography and history toward photography; and romance toward an even mix. The prompt specifies the exact title and author name as cover typography and bans watermarks. Generated images are decoded from base64, converted to optimised progressive JPEG via Pillow (quality 92), and saved as <code>book_{id}.jpg</code>. The pipeline allows two attempts; if both fail, the entire book-generation transaction is rolled back so that no coverless book can enter the database.<br />
<br />
=== Author-photo generation ===<br />
<br />
After a successful cover, the pipeline checks whether the author already has a portrait. If not, it sends a prompt to <code>gpt-image-1</code> for a photorealistic head-and-shoulders portrait at 1024 × 1024 pixels. The result is centre-cropped to a 512 × 512 square JPEG and saved as <code>author_{id}.jpg</code>. Unlike cover generation, photo generation is non-blocking: failures are logged but do not abort the job. In the interface, authors without photos receive a CSS-generated avatar showing their initials.<br />
<br />
=== Error handling and transaction safety ===<br />
<br />
If any exception occurs during book creation, review insertion, or image generation, the pipeline issues an immediate <code>db.session.rollback()</code> to discard all uncommitted data. The ''GenerationJob'' and ''GenerationLog'' records — committed in an earlier transaction — survive, so the failure is auditable. The job is marked as failed with a descriptive error message. In templates, all cover <code>&lt;img&gt;</code> tags include an <code>onerror</code> handler that replaces a broken image with a CSS gradient placeholder bearing the book's title, as a defence against stale database references to missing files.<br />
<br />
== Daily batch generation ==<br />
<br />
A standalone script, <code>fast_generator.py</code>, generates twelve book seeds (title, author, genre) in a single GPT-5 API call lasting roughly twelve seconds. The batch pipeline incorporates several layers of anti-repetition machinery.<br />
<br />
=== Goodreads title inspiration ===<br />
<br />
Before prompting, the script scrapes two to three randomly chosen genre pages on [[Goodreads]] (from a pool of eight: historical fiction, history, fantasy, science fiction, romance, cookbooks, general fiction, and horror). It extracts book titles from <code>div.bookBox img[alt]</code> elements, cleans them of series numbers, author suffixes, and emoji, and presents a sample as "inspiration titles — for tone and flavour only, not to be reproduced." If Goodreads is unreachable, the script falls back to a curated JSON file of titles harvested from the [[Internet Archive]] and [[Open Library]].<br />
<br />
=== Anti-sameness system ===<br />
<br />
To prevent the model from gravitating toward a narrow band of title shapes, the script enforces structural diversity through five mechanisms:<br />
<br />
# '''Title-class rotation.''' Ten structural classes — concrete object, place or institution, named person, event or incident, documentary phrase, odd juxtaposition, fragment or question, subtitle-led, idiomatic phrase, and one-word punch — are allocated evenly across the batch so that each slot has a designated shape.<br />
# '''Avoidance guidance.''' The script analyses a rolling memory of up to 2,000 previously generated titles (persisted in a JSON file) plus all titles already in the database. It identifies the twenty most overused content words, the most common title frames (e.g., "The Last ___," "Beyond the ___"), the most frequent opening words, and the most frequent closing nouns, and encodes these as explicit "do not use" directives in the prompt.<br />
# '''Batch validator.''' After generation, each title in the batch is scored for repetitiveness: collisions on first word, end noun, or structural frame within the batch incur penalties of 0.5–1.5 points; matches against historical overuse patterns add further penalties; and two-word titles composed entirely of generic mood words score a 2.0 penalty. Titles exceeding a cumulative penalty of 3.0 are rejected and regenerated.<br />
# '''Title memory.''' Accepted titles are appended to the rolling memory file (capped at 2,000 entries, oldest dropped first) and checked against the database to prevent exact duplicates.<br />
# '''Database deduplication.''' Each final title is compared case-insensitively to every existing book in the database; duplicates are silently skipped.<br />
<br />
The output is written to <code>daily_books.json</code>, a flat array of title/author/genre objects with generation timestamps.<br />
<br />
=== Hourly processing ===<br />
<br />
A companion script, <code>simple_hourly_processor.py</code>, runs once per hour via cron. It selects one book from the daily JSON file — indexed by a hash of the current date and hour — and triggers its full generation (metadata, reviews, cover, author photo) by calling the application's <code>/cron/hourly_book_full</code> endpoint. If all twelve daily seeds have already been processed, the hour is skipped. In production, a typical crontab runs the batch generator daily at midnight and the hourly processor every other hour, yielding up to twelve new books per day.<br />
<br />
== Cron security ==<br />
<br />
Cron endpoints are protected by a localhost check: the request's client IP must be <code>127.0.0.1</code>, <code>::1</code>, or <code>localhost</code>. For deployments where the cron job calls the public URL rather than the loopback address, two overrides are available: an <code>X-API-Key</code> header (or <code>api_key</code> query parameter) checked against an environment variable, or a global <code>DISABLE_CRON_LOCALHOST_CHECK</code> flag.<br />
<br />
== Public interface ==<br />
<br />
=== Home page ===<br />
<br />
The home page displays a hero section with the title "Possible Books," a rotating tagline (changed every thirty minutes, seeded by the current UTC half-hour), and a generation form with an autocomplete datalist of existing authors. Below the form, a grid of the twelve most recent books (with cover images or gradient fallbacks) appears alongside the twenty-five most recent reviews, sorted by review date.<br />
<br />
=== Book pages ===<br />
<br />
Each book page shows the cover image (or fallback), title, author byline linked to the author's page, genre tag, page count, publication date, and average star rating. The synopsis and author biography are rendered from Markdown. Below, reviews are listed with reviewer name, star display (filled and hollow star characters), review date, and Markdown-formatted review text. Administrators see additional controls: edit book, regenerate cover, delete book, regenerate reviews, and recalculate rating.<br />
<br />
=== Author pages ===<br />
<br />
The author page displays the portrait (or a CSS initials placeholder), the full Markdown biography, and a grid of the author's books. The authors index lists all authors sorted alphabetically by surname, with a plaintext preview of each biography (Markdown rendered, tags stripped, truncated to 100 characters).<br />
<br />
=== Archive ===<br />
<br />
The archive page presents a paginated, filterable grid of all books. A sidebar offers filters by publication-year range (dynamically bucketed), minimum average rating (one to five stars), and genre (checkboxes, grouped by popularity). Filters are applied via form auto-submission on change; an explicit "clear filters" link resets the view.<br />
<br />
=== Genres ===<br />
<br />
The genres page lists all active genres alphabetically with book counts.<br />
<br />
=== Theme ===<br />
<br />
The site defaults to a dark colour scheme (<code>#111315</code> background, <code>#e6e6e6</code> text) and supports a light mode toggled via a moon-icon button in the masthead, persisted in <code>localStorage</code>. The toggle respects the operating system's <code>prefers-color-scheme</code> setting as a default. Typography uses Roboto Serif for display headings and Roboto for body text and UI elements.<br />
<br />
== Progressive web application ==<br />
<br />
The site ships a Web App Manifest declaring standalone display mode, dark background and theme colours, and maskable icons at 192 and 512 pixels. A service worker registers at the root scope but operates in passthrough mode — all fetch events are returned unmodified — to satisfy PWA installability requirements without risking stale cached pages in a database-backed application that publishes new content hourly.<br />
<br />
== See also ==<br />
<br />
* [[Procedural generation]]<br />
* [[Flask (web framework)]]<br />
* [[OpenAI]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Yusupov.cloud&diff=398Yusupov.cloud2026-04-13T13:05:02Z<p>Mvuijlst: /* Subdomains and projects */</p>
<hr />
<div>{{Infobox<br />
| name = yusupov.cloud<br />
| 1 url = https://yusupov.cloud<br />
| 2 type = Personal web sites<br />
| 3 owner = [[Michel Vuijlsteke]]<br />
| 4 launched = 2025<br />
| 5 current_status = Online<br />
}}<br />
<br />
'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref><br />
<br />
== Overview ==<br />
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref><br />
<br />
== Subdomains and projects ==<br />
Publicly visible projects include:<br />
<br />
* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref><br />
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref><br />
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref><br />
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''Digest'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref><br />
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref><br />
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''[[Quidlibet]]'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref><br />
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''[[Thousand Year Old Vampire]]'', with Django 5 backend and Vue 3 frontend. (Per operator.)<br />
<br />
Operator-reported (not publicly discoverable at time of writing):<br />
<br />
* skills.yusupov.cloud — a skills matrix application. (Per operator.)<br />
* resources.yusupov.cloud — a simple resource plannign calendar. (Per operator.)<br />
<br />
== Technology ==<br />
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" /><br />
<br />
== Relation to the BBS ==<br />
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref><br />
<br />
== See also ==<br />
* [[Yusupov's House]] (1990s BBS)<br />
* [[Michel Vuijlsteke]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Personal websites]]<br />
[[Category:Belgian websites]]<br />
[[Category:2025 establishments in Belgium]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Yusupov.cloud&diff=397Yusupov.cloud2026-04-13T09:30:34Z<p>Mvuijlst: /* Subdomains and projects */</p>
<hr />
<div>{{Infobox<br />
| name = yusupov.cloud<br />
| 1 url = https://yusupov.cloud<br />
| 2 type = Personal web sites<br />
| 3 owner = [[Michel Vuijlsteke]]<br />
| 4 launched = 2025<br />
| 5 current_status = Online<br />
}}<br />
<br />
'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref><br />
<br />
== Overview ==<br />
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref><br />
<br />
== Subdomains and projects ==<br />
Publicly visible projects include:<br />
<br />
* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref><br />
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref><br />
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref><br />
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''Digest'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref><br />
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref><br />
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''Quidlibet'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref><br />
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''[[Thousand Year Old Vampire]]'', with Django 5 backend and Vue 3 frontend. (Per operator.)<br />
<br />
Operator-reported (not publicly discoverable at time of writing):<br />
<br />
* skills.yusupov.cloud — a skills matrix application. (Per operator.)<br />
* resources.yusupov.cloud — a simple resource plannign calendar. (Per operator.)<br />
<br />
== Technology ==<br />
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" /><br />
<br />
== Relation to the BBS ==<br />
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref><br />
<br />
== See also ==<br />
* [[Yusupov's House]] (1990s BBS)<br />
* [[Michel Vuijlsteke]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Personal websites]]<br />
[[Category:Belgian websites]]<br />
[[Category:2025 establishments in Belgium]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=File:Tyov-story.jpg&diff=396File:Tyov-story.jpg2026-04-12T11:46:41Z<p>Mvuijlst: </p>
<hr />
<div></div>Mvuijlsthttps://yusupov.cloud/index.php?title=File:Tyov-prompt.jpg&diff=395File:Tyov-prompt.jpg2026-04-12T11:45:53Z<p>Mvuijlst: </p>
<hr />
<div></div>Mvuijlsthttps://yusupov.cloud/index.php?title=File:Tyov-home.jpg&diff=394File:Tyov-home.jpg2026-04-12T11:45:22Z<p>Mvuijlst: </p>
<hr />
<div></div>Mvuijlsthttps://yusupov.cloud/index.php?title=Thousand_Year_Old_Vampire&diff=393Thousand Year Old Vampire2026-04-12T11:45:01Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox <br />
| 01_name = Thousand Year Old Vampire - Web Helper<br />
| 02_developer = Michel Vuijlsteke<br />
| 03_programming language = Python, TypeScript<br />
| 04_operating system = Cross-platform (Web)<br />
| 05_genre = Solo RPG digital companion<br />
| 06_license = Custom<br />
| 07_website = <code>https://tyov.yusupov.cloud</code><br />
}}<br />
<br />
'''Thousand Year Old Vampire - Web Helper''' ('''TYOV-Web''') is a browser-based adaptation of the solo role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. Rather than presenting the game as a digital board game or a rules spreadsheet, it treats a campaign as a long, accumulating chronicle: a vampire begins with a handful of memories, gains new experiences, loses old ones, and leaves behind a life story made of fragments, scars, names, and vanished centuries. The application is built as a '''Django''' backend serving a '''Vue''' single-page frontend, but its real achievement is literary rather than merely technical: it turns bookkeeping-heavy solo play into something that feels legible, mournful, and continuous.<br />
<br />
[[File:tyov-home.jpg|thumb|center|900px|The TYOV-Web home page, where players can browse existing chronicles, continue unfinished character creation, or begin a new vampire.]]<br />
<br />
== Premise ==<br />
<br />
In ''Thousand Year Old Vampire'', the player does not manage hit points, armies, or territory. Instead, the player manages '''memory'''. A vampire may survive for centuries, but cannot perfectly retain those centuries. New experiences force older ones aside. Friends die. Languages decay. Identities are traded, abandoned, or forgotten. The drama comes from watching the self narrow and distort over time.<br />
<br />
TYOV-Web preserves that central idea. A player creates a vampire from mortal beginnings, plays through prompts generated by dice rolls, writes narrative responses to those prompts, and organises the resulting fragments into memories. Over time the character collects skills, resources, marks, and known companions, but those are unstable possessions. The most important question is never simply ''what happened?'' It is ''what can still be remembered?''<br />
<br />
== How Play Works ==<br />
<br />
The application follows the structure of the tabletop game closely, but presents it as a guided story engine. Character creation unfolds in six stages: mortal life, mortal relationships, skills, resources, a defining early experience, and finally the turning into vampirism. Once play begins, each turn revolves around a prompt. The player reads the current prompt, writes at least one experience in response, manages any consequences on the character sheet, then rolls a ten-sided die and a six-sided die to discover the next destination in the prompt list.<br />
<br />
[[File:tyov-prompt.jpg|thumb|right|500px|A prompt page during play. The current prompt, experience form, memories, characters, and skills are visible at the same time, emphasizing both story writing and memory pressure.]]<br />
<br />
That movement is what gives the game its broken historical rhythm. A positive result on D10 minus D6 pushes the vampire forward; a negative result drags the story backward into earlier themes or alternative branches. Prompts are also divided into variations, so revisiting a number does not necessarily mean revisiting the same moment in the same way.<br />
<br />
The memory system gives the application its emotional pressure. A character can normally hold only '''five active memories''', and each memory can contain no more than '''three experiences'''. When that limit is reached, the player must decide what to lose. Some memories can be moved into a '''diary''', which acts as an external repository, but diaries themselves are only resources, and resources can be lost. The result is a game about narrative curation: the player is constantly deciding which version of the vampire's past deserves to remain visible.<br />
<br />
Special prompts can alter that rhythm. Some disable experience-writing for a turn. Others allow the vampire's name to change, permit the editing of old experiences, reduce or increase permanent memory capacity, or end the chronicle entirely with an epilogue.<br />
<br />
== An Example Unlife: Karmis ==<br />
<br />
The most compelling way to understand the application is through one of its stored characters. One campaign in the database follows '''Karmis''', formerly '''Ekurzu''' and before that '''Naram''', across roughly three and a half thousand years.<br />
<br />
[[File:tyov-story.jpg|thumb|right|500px|The story overview view presents a character's life as a readable timeline, combining narrative entries with a compact summary of memories, experiences, characters, skills, resources, and marks.]]<br />
<br />
He begins in Bronze Age Mari as a temple scribe: precise, observant, and deeply embedded in the religious and political machinery of the city. His mortal life is defined by clay tablets, whispered intelligence, and courtly danger. He falls in love with Hessa, is shaped by the mentorship of the high priest Ibbi-Zamri, and is eventually turned by the ancient vampire Ashurban the Veiled. In one of the campaign's defining cruelties, Ibbi-Zamri becomes the first person Karmis kills after the turning.<br />
<br />
The early centuries of his unlife are marked by exile and shame. He flees with Ennatum, struggles to master the hunger, tries to imagine restraint as redemption, and fails. One of the campaign's most effective lines comes from this period: he builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually he devours Ennatum during a sandstorm and carries that loss into the long middle stretch of the story.<br />
<br />
From there the campaign moves through one civilisation after another. Karmis passes through Akhenaten's Egypt, the imperial roads of the Achaemenids, the scholarly world of Alexandria, Roman frontiers, monastic Europe, Mediterranean trade routes, and the violence of the early modern Atlantic world. His roles change less than the world around him does. He remains a scribe, witness, forger, archivist, and careful observer of institutions that never last as long as he does.<br />
<br />
The campaign also shows how the game's systems create character rather than merely recording it. Karmis gains skills such as ''Silent Cartography'', the ability to trace unseen paths of influence, and ''Ash-Tongue'', a talent for insinuation and social survival. But he loses others as time damages his identity. He once knew how to decipher ancient texts; later he no longer can. He once believed he could control the beast within; later even that confidence disappears. The mechanics translate immortality into erosion.<br />
<br />
One of the campaign's richest relationships is with '''Thooni''', a scholar who recognises the name ''Ekurzu'' not as legend but as continuity. After her mortal death, the relationship persists in altered form: a spectral Thooni begins appearing in the margins of Karmis's diary, leaving fragments in languages he can no longer read. TYOV-Web handles this elegantly because its model of a character is not limited to a living cast list. People can be present, absent, lost, remembered, or transformed into symbols the protagonist can no longer fully interpret.<br />
<br />
By the late Roman and early medieval portions of the chronicle, the cost of the memory rules becomes brutal. Karmis loses so many memories that even the event of his own turning is no longer available to him. He relies on diaries and external records to stabilise himself, yet those too are vulnerable. A carved chamber called ''The Walls of Forgetting'' and a later monastery diary both disappear. The application does not treat this as simple inventory loss; it feels instead like a second death for pieces of the self.<br />
<br />
In the final act, Karmis witnesses the Atlantic slave trade and begins keeping a ledger of names drawn from shipping manifests and punishment records. A later response captures the moral exhaustion of the character with unusual sharpness: he no longer imagines himself purified by restraint, only redirected by purpose. He feeds on slavers and calls it justice, yet recognises that the blood tastes the same. This is the kind of line the application is built to preserve: not just event logs, but accumulations of ethical fatigue.<br />
<br />
His last great companion is '''Mirelde of Bracha''', who becomes mirror, partner, and eventually historian. By the time the epilogue arrives, the story is no longer told in Karmis's own voice. Mirelde writes the closing judgment on him: not as a monster laid to rest, but as "just a man who remembered too much, for too long, and chose, in the end, peace." That shift in narrator is exactly the sort of late-game turn TYOV-Web makes easy to sustain, because it keeps the campaign legible even after the protagonist himself has become unreliable.<br />
<br />
== Why the Application Works ==<br />
<br />
What makes TYOV-Web effective is not that it digitises every rule, though it largely does. Its strength is that it understands which parts of the original game are dramatically important and places those at the centre of the interface.<br />
<br />
The main play screen is organised around the prompt, the character sheet, and the memory display. The prompt is always the immediate literary provocation. The memory display constantly reminds the player of pressure and loss: active memories, diary memories, and forgotten memories sit in visible relation to one another. Skills, resources, marks, and known characters are editable in place, which means the character sheet grows and collapses alongside the fiction instead of feeling like a separate administrative surface.<br />
<br />
The result is a frontend that behaves less like a dashboard and more like a writing desk. Players move between the prompt text, the experience form, and the fragments of the vampire's surviving life. Even when the application is doing something purely mechanical, such as validating whether the player may continue, the effect is narrative: it is asking whether the current moment of the story has been fully accounted for.<br />
<br />
== The Frontend as Chronicle ==<br />
<br />
The client side of TYOV-Web is a '''Vue 3''' single-page application written in '''TypeScript'''. In practical terms, this means the entire experience unfolds without page reloads; in literary terms, it allows the game to feel continuous. The player logs in, sees a home screen of active and archived characters, enters a creation wizard for new vampires, and then spends most of the campaign inside a single evolving game view.<br />
<br />
That view is supported by a set of focused screens: a login page, a home dashboard, the six-step character creation flow, the main game interface, an ending screen for completed chronicles, an archive view, and a story view that presents the campaign as a timeline. Around those are a collection of smaller windows and dialogs for editing characters, skills, resources, memories, and experiences. These are important not because there are many of them, but because they preserve the sense that a campaign is always open to revision, annotation, and reinterpretation.<br />
<br />
State is held in Pinia stores for authentication, gameplay, character creation, and theme. That is an implementation detail, but in this case it serves a visible purpose: it keeps the player's character, current prompt, pending changes, and validation state coherent at all times. The interface never feels as if it has forgotten where the player is in the life of the vampire.<br />
<br />
== The Backend as Memory Keeper ==<br />
<br />
Behind the interface is a '''Django 5''' application with a REST API built on '''Django REST Framework'''. The backend models the campaign in the same terms the game itself cares about: '''Character''', '''Memory''', '''Experience''', '''Skill''', '''Resource''', '''Mark''', '''GameCharacter''', '''Prompt''', and '''PendingChange'''. This is not especially glamorous architecture, but it is disciplined. The data model is close to the language of play, which makes the whole system easier to reason about.<br />
<br />
The most interesting design choice is the use of '''pending changes'''. TYOV-Web does not immediately finalise every action the player takes. Instead, new experiences and character-sheet adjustments can accumulate as provisional edits until the player chooses to continue the story. Only then are they committed atomically. This makes the system feel less like a CRUD application and more like a drafting process. A turn can be assembled, reconsidered, and only then sealed into the chronicle.<br />
<br />
Authentication is handled by JWT tokens, and character data is scoped to the authenticated user. The backend exposes endpoints for the game state itself, dice rolling, story continuation, and CRUD operations on memories, experiences, skills, resources, marks, and known characters. In the article, however, the important point is not the shape of the URLs. It is that the backend has been designed to support a narrative workflow rather than a generic records system.<br />
<br />
== Audit Trail ==<br />
<br />
One of the application's strongest features is its audit trail. Each time the player advances to a new prompt, TYOV-Web captures a complete snapshot of the game state: prompt transition, dice roll, character sheet, memories, and the set of changes applied on that turn. In effect, the application keeps both the ''current'' vampire and the ''history of how that vampire became current''.<br />
<br />
This matters for more than debugging. In a game built around forgetting, a turn-by-turn archive becomes part of the theme. The player may choose to lose a memory inside the fiction, but the application still preserves the fact that the loss occurred. The vampire forgets; the chronicle does not.<br />
<br />
== Development and Deployment ==<br />
<br />
TYOV-Web is developed as a two-part web project: Django on the server side, Vue on the client side. In local development the repository can be started with a PowerShell bootstrap script, which creates the Python environment, installs dependencies, runs migrations, and launches both servers. In production, the frontend is built with Vite and the backend is configured through the usual Django environment settings, including a production mode selected with <code>DJANGO_ENV=production</code>.<br />
<br />
Testing exists on both sides of the stack. The backend is covered with '''pytest''' and '''pytest-django'''; the frontend uses '''Playwright''' for end-to-end coverage of the creation flow and core game loop. Those details are reassuring, but secondary. The more meaningful point is that the project has been built as an actual maintained application rather than a one-off prototype.<br />
<br />
== Reception Within the Project ==<br />
<br />
As a fan-made implementation, TYOV-Web is best understood as an act of interpretation. It does not try to replace the tabletop experience with spectacle. Instead it asks what a web application can do well for this particular game: preserve long-form writing, reduce clerical overhead, make memory pressure visible, and retain the full history of a life that the protagonist can no longer fully remember. In that sense it is not merely a helper app. It is a machine for turning play into biography.<br />
<br />
== See Also ==<br />
<br />
* ''Thousand Year Old Vampire'' by Tim Hutchings<br />
* [[Django (web framework)]]<br />
* [[Vue.js]]<br />
* [[Single-page application]]<br />
<br />
== References ==<br />
<br />
{{Reflist}}<br />
<br />
[[Category:Web applications]]<br />
[[Category:Role-playing video games]]<br />
[[Category:Django (web framework) applications]]<br />
[[Category:Vue.js applications]]<br />
[[Category:Solo role-playing games]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Thousand_Year_Old_Vampire&diff=392Thousand Year Old Vampire2026-04-12T11:34:54Z<p>Mvuijlst: /* How Play Works */</p>
<hr />
<div>{{Infobox <br />
| 01_name = Thousand Year Old Vampire - Web Helper<br />
| 02_developer = Michel Vuijlsteke<br />
| 03_programming language = Python, TypeScript<br />
| 04_operating system = Cross-platform (Web)<br />
| 05_genre = Solo RPG digital companion<br />
| 06_license = Custom<br />
| 07_website = <code>https://tyov.yusupov.cloud</code><br />
}}<br />
<br />
'''Thousand Year Old Vampire - Web Helper''' ('''TYOV-Web''') is a browser-based adaptation of the solo role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. Rather than presenting the game as a digital board game or a rules spreadsheet, it treats a campaign as a long, accumulating chronicle: a vampire begins with a handful of memories, gains new experiences, loses old ones, and leaves behind a life story made of fragments, scars, names, and vanished centuries. The application is built as a '''Django''' backend serving a '''Vue''' single-page frontend, but its real achievement is literary rather than merely technical: it turns bookkeeping-heavy solo play into something that feels legible, mournful, and continuous.<br />
<br />
== Premise ==<br />
<br />
In ''Thousand Year Old Vampire'', the player does not manage hit points, armies, or territory. Instead, the player manages '''memory'''. A vampire may survive for centuries, but cannot perfectly retain those centuries. New experiences force older ones aside. Friends die. Languages decay. Identities are traded, abandoned, or forgotten. The drama comes from watching the self narrow and distort over time.<br />
<br />
TYOV-Web preserves that central idea. A player creates a vampire from mortal beginnings, plays through prompts generated by dice rolls, writes narrative responses to those prompts, and organises the resulting fragments into memories. Over time the character collects skills, resources, marks, and known companions, but those are unstable possessions. The most important question is never simply ''what happened?'' It is ''what can still be remembered?''<br />
<br />
== How Play Works ==<br />
<br />
The application follows the structure of the tabletop game closely, but presents it as a guided story engine. Character creation unfolds in six stages: mortal life, mortal relationships, skills, resources, a defining early experience, and finally the turning into vampirism. Once play begins, each turn revolves around a prompt. The player reads the current prompt, writes at least one experience in response, manages any consequences on the character sheet, then rolls a ten-sided die and a six-sided die to discover the next destination in the prompt list.<br />
<br />
That movement is what gives the game its broken historical rhythm. A positive result on D10 minus D6 pushes the vampire forward; a negative result drags the story backward into earlier themes or alternative branches. Prompts are also divided into variations, so revisiting a number does not necessarily mean revisiting the same moment in the same way.<br />
<br />
The memory system gives the application its emotional pressure. A character can normally hold only '''five active memories''', and each memory can contain no more than '''three experiences'''. When that limit is reached, the player must decide what to lose. Some memories can be moved into a '''diary''', which acts as an external repository, but diaries themselves are only resources, and resources can be lost. The result is a game about narrative curation: the player is constantly deciding which version of the vampire's past deserves to remain visible.<br />
<br />
Special prompts can alter that rhythm. Some disable experience-writing for a turn. Others allow the vampire's name to change, permit the editing of old experiences, reduce or increase permanent memory capacity, or end the chronicle entirely with an epilogue.<br />
<br />
== An Example Unlife: Karmis ==<br />
<br />
The most compelling way to understand the application is through one of its stored characters. One campaign in the database follows '''Karmis''', formerly '''Ekurzu''' and before that '''Naram''', across roughly three and a half thousand years.<br />
<br />
He begins in Bronze Age Mari as a temple scribe: precise, observant, and deeply embedded in the religious and political machinery of the city. His mortal life is defined by clay tablets, whispered intelligence, and courtly danger. He falls in love with Hessa, is shaped by the mentorship of the high priest Ibbi-Zamri, and is eventually turned by the ancient vampire Ashurban the Veiled. In one of the campaign's defining cruelties, Ibbi-Zamri becomes the first person Karmis kills after the turning.<br />
<br />
The early centuries of his unlife are marked by exile and shame. He flees with Ennatum, struggles to master the hunger, tries to imagine restraint as redemption, and fails. One of the campaign's most effective lines comes from this period: he builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually he devours Ennatum during a sandstorm and carries that loss into the long middle stretch of the story.<br />
<br />
From there the campaign moves through one civilisation after another. Karmis passes through Akhenaten's Egypt, the imperial roads of the Achaemenids, the scholarly world of Alexandria, Roman frontiers, monastic Europe, Mediterranean trade routes, and the violence of the early modern Atlantic world. His roles change less than the world around him does. He remains a scribe, witness, forger, archivist, and careful observer of institutions that never last as long as he does.<br />
<br />
The campaign also shows how the game's systems create character rather than merely recording it. Karmis gains skills such as ''Silent Cartography'', the ability to trace unseen paths of influence, and ''Ash-Tongue'', a talent for insinuation and social survival. But he loses others as time damages his identity. He once knew how to decipher ancient texts; later he no longer can. He once believed he could control the beast within; later even that confidence disappears. The mechanics translate immortality into erosion.<br />
<br />
One of the campaign's richest relationships is with '''Thooni''', a scholar who recognises the name ''Ekurzu'' not as legend but as continuity. After her mortal death, the relationship persists in altered form: a spectral Thooni begins appearing in the margins of Karmis's diary, leaving fragments in languages he can no longer read. TYOV-Web handles this elegantly because its model of a character is not limited to a living cast list. People can be present, absent, lost, remembered, or transformed into symbols the protagonist can no longer fully interpret.<br />
<br />
By the late Roman and early medieval portions of the chronicle, the cost of the memory rules becomes brutal. Karmis loses so many memories that even the event of his own turning is no longer available to him. He relies on diaries and external records to stabilise himself, yet those too are vulnerable. A carved chamber called ''The Walls of Forgetting'' and a later monastery diary both disappear. The application does not treat this as simple inventory loss; it feels instead like a second death for pieces of the self.<br />
<br />
In the final act, Karmis witnesses the Atlantic slave trade and begins keeping a ledger of names drawn from shipping manifests and punishment records. A later response captures the moral exhaustion of the character with unusual sharpness: he no longer imagines himself purified by restraint, only redirected by purpose. He feeds on slavers and calls it justice, yet recognises that the blood tastes the same. This is the kind of line the application is built to preserve: not just event logs, but accumulations of ethical fatigue.<br />
<br />
His last great companion is '''Mirelde of Bracha''', who becomes mirror, partner, and eventually historian. By the time the epilogue arrives, the story is no longer told in Karmis's own voice. Mirelde writes the closing judgment on him: not as a monster laid to rest, but as "just a man who remembered too much, for too long, and chose, in the end, peace." That shift in narrator is exactly the sort of late-game turn TYOV-Web makes easy to sustain, because it keeps the campaign legible even after the protagonist himself has become unreliable.<br />
<br />
== Why the Application Works ==<br />
<br />
What makes TYOV-Web effective is not that it digitises every rule, though it largely does. Its strength is that it understands which parts of the original game are dramatically important and places those at the centre of the interface.<br />
<br />
The main play screen is organised around the prompt, the character sheet, and the memory display. The prompt is always the immediate literary provocation. The memory display constantly reminds the player of pressure and loss: active memories, diary memories, and forgotten memories sit in visible relation to one another. Skills, resources, marks, and known characters are editable in place, which means the character sheet grows and collapses alongside the fiction instead of feeling like a separate administrative surface.<br />
<br />
The result is a frontend that behaves less like a dashboard and more like a writing desk. Players move between the prompt text, the experience form, and the fragments of the vampire's surviving life. Even when the application is doing something purely mechanical, such as validating whether the player may continue, the effect is narrative: it is asking whether the current moment of the story has been fully accounted for.<br />
<br />
== The Frontend as Chronicle ==<br />
<br />
The client side of TYOV-Web is a '''Vue 3''' single-page application written in '''TypeScript'''. In practical terms, this means the entire experience unfolds without page reloads; in literary terms, it allows the game to feel continuous. The player logs in, sees a home screen of active and archived characters, enters a creation wizard for new vampires, and then spends most of the campaign inside a single evolving game view.<br />
<br />
That view is supported by a set of focused screens: a login page, a home dashboard, the six-step character creation flow, the main game interface, an ending screen for completed chronicles, an archive view, and a story view that presents the campaign as a timeline. Around those are a collection of smaller windows and dialogs for editing characters, skills, resources, memories, and experiences. These are important not because there are many of them, but because they preserve the sense that a campaign is always open to revision, annotation, and reinterpretation.<br />
<br />
State is held in Pinia stores for authentication, gameplay, character creation, and theme. That is an implementation detail, but in this case it serves a visible purpose: it keeps the player's character, current prompt, pending changes, and validation state coherent at all times. The interface never feels as if it has forgotten where the player is in the life of the vampire.<br />
<br />
== The Backend as Memory Keeper ==<br />
<br />
Behind the interface is a '''Django 5''' application with a REST API built on '''Django REST Framework'''. The backend models the campaign in the same terms the game itself cares about: '''Character''', '''Memory''', '''Experience''', '''Skill''', '''Resource''', '''Mark''', '''GameCharacter''', '''Prompt''', and '''PendingChange'''. This is not especially glamorous architecture, but it is disciplined. The data model is close to the language of play, which makes the whole system easier to reason about.<br />
<br />
The most interesting design choice is the use of '''pending changes'''. TYOV-Web does not immediately finalise every action the player takes. Instead, new experiences and character-sheet adjustments can accumulate as provisional edits until the player chooses to continue the story. Only then are they committed atomically. This makes the system feel less like a CRUD application and more like a drafting process. A turn can be assembled, reconsidered, and only then sealed into the chronicle.<br />
<br />
Authentication is handled by JWT tokens, and character data is scoped to the authenticated user. The backend exposes endpoints for the game state itself, dice rolling, story continuation, and CRUD operations on memories, experiences, skills, resources, marks, and known characters. In the article, however, the important point is not the shape of the URLs. It is that the backend has been designed to support a narrative workflow rather than a generic records system.<br />
<br />
== Audit Trail ==<br />
<br />
One of the application's strongest features is its audit trail. Each time the player advances to a new prompt, TYOV-Web captures a complete snapshot of the game state: prompt transition, dice roll, character sheet, memories, and the set of changes applied on that turn. In effect, the application keeps both the ''current'' vampire and the ''history of how that vampire became current''.<br />
<br />
This matters for more than debugging. In a game built around forgetting, a turn-by-turn archive becomes part of the theme. The player may choose to lose a memory inside the fiction, but the application still preserves the fact that the loss occurred. The vampire forgets; the chronicle does not.<br />
<br />
== Development and Deployment ==<br />
<br />
TYOV-Web is developed as a two-part web project: Django on the server side, Vue on the client side. In local development the repository can be started with a PowerShell bootstrap script, which creates the Python environment, installs dependencies, runs migrations, and launches both servers. In production, the frontend is built with Vite and the backend is configured through the usual Django environment settings, including a production mode selected with <code>DJANGO_ENV=production</code>.<br />
<br />
Testing exists on both sides of the stack. The backend is covered with '''pytest''' and '''pytest-django'''; the frontend uses '''Playwright''' for end-to-end coverage of the creation flow and core game loop. Those details are reassuring, but secondary. The more meaningful point is that the project has been built as an actual maintained application rather than a one-off prototype.<br />
<br />
== Reception Within the Project ==<br />
<br />
As a fan-made implementation, TYOV-Web is best understood as an act of interpretation. It does not try to replace the tabletop experience with spectacle. Instead it asks what a web application can do well for this particular game: preserve long-form writing, reduce clerical overhead, make memory pressure visible, and retain the full history of a life that the protagonist can no longer fully remember. In that sense it is not merely a helper app. It is a machine for turning play into biography.<br />
<br />
== See Also ==<br />
<br />
* ''Thousand Year Old Vampire'' by Tim Hutchings<br />
* [[Django (web framework)]]<br />
* [[Vue.js]]<br />
* [[Single-page application]]<br />
<br />
== References ==<br />
<br />
{{Reflist}}<br />
<br />
[[Category:Web applications]]<br />
[[Category:Role-playing video games]]<br />
[[Category:Django (web framework) applications]]<br />
[[Category:Vue.js applications]]<br />
[[Category:Solo role-playing games]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Thousand_Year_Old_Vampire&diff=391Thousand Year Old Vampire2026-04-12T11:34:07Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox <br />
| 01_name = Thousand Year Old Vampire - Web Helper<br />
| 02_developer = Michel Vuijlsteke<br />
| 03_programming language = Python, TypeScript<br />
| 04_operating system = Cross-platform (Web)<br />
| 05_genre = Solo RPG digital companion<br />
| 06_license = Custom<br />
| 07_website = <code>https://tyov.yusupov.cloud</code><br />
}}<br />
<br />
'''Thousand Year Old Vampire - Web Helper''' ('''TYOV-Web''') is a browser-based adaptation of the solo role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. Rather than presenting the game as a digital board game or a rules spreadsheet, it treats a campaign as a long, accumulating chronicle: a vampire begins with a handful of memories, gains new experiences, loses old ones, and leaves behind a life story made of fragments, scars, names, and vanished centuries. The application is built as a '''Django''' backend serving a '''Vue''' single-page frontend, but its real achievement is literary rather than merely technical: it turns bookkeeping-heavy solo play into something that feels legible, mournful, and continuous.<br />
<br />
== Premise ==<br />
<br />
In ''Thousand Year Old Vampire'', the player does not manage hit points, armies, or territory. Instead, the player manages '''memory'''. A vampire may survive for centuries, but cannot perfectly retain those centuries. New experiences force older ones aside. Friends die. Languages decay. Identities are traded, abandoned, or forgotten. The drama comes from watching the self narrow and distort over time.<br />
<br />
TYOV-Web preserves that central idea. A player creates a vampire from mortal beginnings, plays through prompts generated by dice rolls, writes narrative responses to those prompts, and organises the resulting fragments into memories. Over time the character collects skills, resources, marks, and known companions, but those are unstable possessions. The most important question is never simply ''what happened?'' It is ''what can still be remembered?''<br />
<br />
== How Play Works ==<br />
<br />
The application follows the structure of the tabletop game closely, but presents it as a guided story engine. Character creation unfolds in six stages: mortal life, mortal relationships, skills, resources, a defining early experience, and finally the turning into vampirism. Once play begins, each turn revolves around a prompt. The player reads the current prompt, writes at least one experience in response, manages any consequences on the character sheet, then rolls a ten-sided die and a six-sided die to discover the next destination in the prompt list.<br />
<br />
That movement is what gives the game its broken historical rhythm. A positive result on D10 minus D6 pushes the vampire forward; a negative result drags the story backward into earlier themes or alternative branches. Prompts are also divided into variations, so revisiting a number does not necessarily mean revisiting the same moment in the same way.<br />
<br />
The memory system gives the application its emotional pressure. A character can normally hold only '''five active memories''', and each memory can contain no more than '''three experiences'''. When that limit is reached, the player must decide what to lose. Some memories can be moved into a '''diary''', which acts as an external repository, but diaries themselves are only resources, and resources can be lost. The result is a game about narrative curation: the player is constantly deciding which version of the vampire's past deserves to remain visible.<br />
<br />
Special prompts can alter that rhythm. Some disable experience-writing for a turn. Others allow the vampire's name to change, permit the editing of old experiences, reduce or increase permanent memory capacity, or end the chronicle entirely with an epilogue. TYOV-Web exposes these rules clearly during play, but the rules never overwhelm the fiction. They exist to sharpen it.<br />
<br />
== An Example Unlife: Karmis ==<br />
<br />
The most compelling way to understand the application is through one of its stored characters. One campaign in the database follows '''Karmis''', formerly '''Ekurzu''' and before that '''Naram''', across roughly three and a half thousand years.<br />
<br />
He begins in Bronze Age Mari as a temple scribe: precise, observant, and deeply embedded in the religious and political machinery of the city. His mortal life is defined by clay tablets, whispered intelligence, and courtly danger. He falls in love with Hessa, is shaped by the mentorship of the high priest Ibbi-Zamri, and is eventually turned by the ancient vampire Ashurban the Veiled. In one of the campaign's defining cruelties, Ibbi-Zamri becomes the first person Karmis kills after the turning.<br />
<br />
The early centuries of his unlife are marked by exile and shame. He flees with Ennatum, struggles to master the hunger, tries to imagine restraint as redemption, and fails. One of the campaign's most effective lines comes from this period: he builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually he devours Ennatum during a sandstorm and carries that loss into the long middle stretch of the story.<br />
<br />
From there the campaign moves through one civilisation after another. Karmis passes through Akhenaten's Egypt, the imperial roads of the Achaemenids, the scholarly world of Alexandria, Roman frontiers, monastic Europe, Mediterranean trade routes, and the violence of the early modern Atlantic world. His roles change less than the world around him does. He remains a scribe, witness, forger, archivist, and careful observer of institutions that never last as long as he does.<br />
<br />
The campaign also shows how the game's systems create character rather than merely recording it. Karmis gains skills such as ''Silent Cartography'', the ability to trace unseen paths of influence, and ''Ash-Tongue'', a talent for insinuation and social survival. But he loses others as time damages his identity. He once knew how to decipher ancient texts; later he no longer can. He once believed he could control the beast within; later even that confidence disappears. The mechanics translate immortality into erosion.<br />
<br />
One of the campaign's richest relationships is with '''Thooni''', a scholar who recognises the name ''Ekurzu'' not as legend but as continuity. After her mortal death, the relationship persists in altered form: a spectral Thooni begins appearing in the margins of Karmis's diary, leaving fragments in languages he can no longer read. TYOV-Web handles this elegantly because its model of a character is not limited to a living cast list. People can be present, absent, lost, remembered, or transformed into symbols the protagonist can no longer fully interpret.<br />
<br />
By the late Roman and early medieval portions of the chronicle, the cost of the memory rules becomes brutal. Karmis loses so many memories that even the event of his own turning is no longer available to him. He relies on diaries and external records to stabilise himself, yet those too are vulnerable. A carved chamber called ''The Walls of Forgetting'' and a later monastery diary both disappear. The application does not treat this as simple inventory loss; it feels instead like a second death for pieces of the self.<br />
<br />
In the final act, Karmis witnesses the Atlantic slave trade and begins keeping a ledger of names drawn from shipping manifests and punishment records. A later response captures the moral exhaustion of the character with unusual sharpness: he no longer imagines himself purified by restraint, only redirected by purpose. He feeds on slavers and calls it justice, yet recognises that the blood tastes the same. This is the kind of line the application is built to preserve: not just event logs, but accumulations of ethical fatigue.<br />
<br />
His last great companion is '''Mirelde of Bracha''', who becomes mirror, partner, and eventually historian. By the time the epilogue arrives, the story is no longer told in Karmis's own voice. Mirelde writes the closing judgment on him: not as a monster laid to rest, but as "just a man who remembered too much, for too long, and chose, in the end, peace." That shift in narrator is exactly the sort of late-game turn TYOV-Web makes easy to sustain, because it keeps the campaign legible even after the protagonist himself has become unreliable.<br />
<br />
== Why the Application Works ==<br />
<br />
What makes TYOV-Web effective is not that it digitises every rule, though it largely does. Its strength is that it understands which parts of the original game are dramatically important and places those at the centre of the interface.<br />
<br />
The main play screen is organised around the prompt, the character sheet, and the memory display. The prompt is always the immediate literary provocation. The memory display constantly reminds the player of pressure and loss: active memories, diary memories, and forgotten memories sit in visible relation to one another. Skills, resources, marks, and known characters are editable in place, which means the character sheet grows and collapses alongside the fiction instead of feeling like a separate administrative surface.<br />
<br />
The result is a frontend that behaves less like a dashboard and more like a writing desk. Players move between the prompt text, the experience form, and the fragments of the vampire's surviving life. Even when the application is doing something purely mechanical, such as validating whether the player may continue, the effect is narrative: it is asking whether the current moment of the story has been fully accounted for.<br />
<br />
== The Frontend as Chronicle ==<br />
<br />
The client side of TYOV-Web is a '''Vue 3''' single-page application written in '''TypeScript'''. In practical terms, this means the entire experience unfolds without page reloads; in literary terms, it allows the game to feel continuous. The player logs in, sees a home screen of active and archived characters, enters a creation wizard for new vampires, and then spends most of the campaign inside a single evolving game view.<br />
<br />
That view is supported by a set of focused screens: a login page, a home dashboard, the six-step character creation flow, the main game interface, an ending screen for completed chronicles, an archive view, and a story view that presents the campaign as a timeline. Around those are a collection of smaller windows and dialogs for editing characters, skills, resources, memories, and experiences. These are important not because there are many of them, but because they preserve the sense that a campaign is always open to revision, annotation, and reinterpretation.<br />
<br />
State is held in Pinia stores for authentication, gameplay, character creation, and theme. That is an implementation detail, but in this case it serves a visible purpose: it keeps the player's character, current prompt, pending changes, and validation state coherent at all times. The interface never feels as if it has forgotten where the player is in the life of the vampire.<br />
<br />
== The Backend as Memory Keeper ==<br />
<br />
Behind the interface is a '''Django 5''' application with a REST API built on '''Django REST Framework'''. The backend models the campaign in the same terms the game itself cares about: '''Character''', '''Memory''', '''Experience''', '''Skill''', '''Resource''', '''Mark''', '''GameCharacter''', '''Prompt''', and '''PendingChange'''. This is not especially glamorous architecture, but it is disciplined. The data model is close to the language of play, which makes the whole system easier to reason about.<br />
<br />
The most interesting design choice is the use of '''pending changes'''. TYOV-Web does not immediately finalise every action the player takes. Instead, new experiences and character-sheet adjustments can accumulate as provisional edits until the player chooses to continue the story. Only then are they committed atomically. This makes the system feel less like a CRUD application and more like a drafting process. A turn can be assembled, reconsidered, and only then sealed into the chronicle.<br />
<br />
Authentication is handled by JWT tokens, and character data is scoped to the authenticated user. The backend exposes endpoints for the game state itself, dice rolling, story continuation, and CRUD operations on memories, experiences, skills, resources, marks, and known characters. In the article, however, the important point is not the shape of the URLs. It is that the backend has been designed to support a narrative workflow rather than a generic records system.<br />
<br />
== Audit Trail ==<br />
<br />
One of the application's strongest features is its audit trail. Each time the player advances to a new prompt, TYOV-Web captures a complete snapshot of the game state: prompt transition, dice roll, character sheet, memories, and the set of changes applied on that turn. In effect, the application keeps both the ''current'' vampire and the ''history of how that vampire became current''.<br />
<br />
This matters for more than debugging. In a game built around forgetting, a turn-by-turn archive becomes part of the theme. The player may choose to lose a memory inside the fiction, but the application still preserves the fact that the loss occurred. The vampire forgets; the chronicle does not.<br />
<br />
== Development and Deployment ==<br />
<br />
TYOV-Web is developed as a two-part web project: Django on the server side, Vue on the client side. In local development the repository can be started with a PowerShell bootstrap script, which creates the Python environment, installs dependencies, runs migrations, and launches both servers. In production, the frontend is built with Vite and the backend is configured through the usual Django environment settings, including a production mode selected with <code>DJANGO_ENV=production</code>.<br />
<br />
Testing exists on both sides of the stack. The backend is covered with '''pytest''' and '''pytest-django'''; the frontend uses '''Playwright''' for end-to-end coverage of the creation flow and core game loop. Those details are reassuring, but secondary. The more meaningful point is that the project has been built as an actual maintained application rather than a one-off prototype.<br />
<br />
== Reception Within the Project ==<br />
<br />
As a fan-made implementation, TYOV-Web is best understood as an act of interpretation. It does not try to replace the tabletop experience with spectacle. Instead it asks what a web application can do well for this particular game: preserve long-form writing, reduce clerical overhead, make memory pressure visible, and retain the full history of a life that the protagonist can no longer fully remember. In that sense it is not merely a helper app. It is a machine for turning play into biography.<br />
<br />
== See Also ==<br />
<br />
* ''Thousand Year Old Vampire'' by Tim Hutchings<br />
* [[Django (web framework)]]<br />
* [[Vue.js]]<br />
* [[Single-page application]]<br />
<br />
== References ==<br />
<br />
{{Reflist}}<br />
<br />
[[Category:Web applications]]<br />
[[Category:Role-playing video games]]<br />
[[Category:Django (web framework) applications]]<br />
[[Category:Vue.js applications]]<br />
[[Category:Solo role-playing games]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Thousand_Year_Old_Vampire&diff=390Thousand Year Old Vampire2026-04-12T11:33:32Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox software<br />
| name = Thousand Year Old Vampire - Web Helper<br />
| developer = Michel Vuijlsteke<br />
| programming language = Python, TypeScript<br />
| operating system = Cross-platform (Web)<br />
| genre = Solo RPG digital companion<br />
| license = Custom<br />
| website = <code>https://tyov.yusupov.cloud</code><br />
}}<br />
<br />
'''Thousand Year Old Vampire - Web Helper''' ('''TYOV-Web''') is a browser-based adaptation of the solo role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. Rather than presenting the game as a digital board game or a rules spreadsheet, it treats a campaign as a long, accumulating chronicle: a vampire begins with a handful of memories, gains new experiences, loses old ones, and leaves behind a life story made of fragments, scars, names, and vanished centuries. The application is built as a '''Django''' backend serving a '''Vue''' single-page frontend, but its real achievement is literary rather than merely technical: it turns bookkeeping-heavy solo play into something that feels legible, mournful, and continuous.<br />
<br />
== Premise ==<br />
<br />
In ''Thousand Year Old Vampire'', the player does not manage hit points, armies, or territory. Instead, the player manages '''memory'''. A vampire may survive for centuries, but cannot perfectly retain those centuries. New experiences force older ones aside. Friends die. Languages decay. Identities are traded, abandoned, or forgotten. The drama comes from watching the self narrow and distort over time.<br />
<br />
TYOV-Web preserves that central idea. A player creates a vampire from mortal beginnings, plays through prompts generated by dice rolls, writes narrative responses to those prompts, and organises the resulting fragments into memories. Over time the character collects skills, resources, marks, and known companions, but those are unstable possessions. The most important question is never simply ''what happened?'' It is ''what can still be remembered?''<br />
<br />
== How Play Works ==<br />
<br />
The application follows the structure of the tabletop game closely, but presents it as a guided story engine. Character creation unfolds in six stages: mortal life, mortal relationships, skills, resources, a defining early experience, and finally the turning into vampirism. Once play begins, each turn revolves around a prompt. The player reads the current prompt, writes at least one experience in response, manages any consequences on the character sheet, then rolls a ten-sided die and a six-sided die to discover the next destination in the prompt list.<br />
<br />
That movement is what gives the game its broken historical rhythm. A positive result on D10 minus D6 pushes the vampire forward; a negative result drags the story backward into earlier themes or alternative branches. Prompts are also divided into variations, so revisiting a number does not necessarily mean revisiting the same moment in the same way.<br />
<br />
The memory system gives the application its emotional pressure. A character can normally hold only '''five active memories''', and each memory can contain no more than '''three experiences'''. When that limit is reached, the player must decide what to lose. Some memories can be moved into a '''diary''', which acts as an external repository, but diaries themselves are only resources, and resources can be lost. The result is a game about narrative curation: the player is constantly deciding which version of the vampire's past deserves to remain visible.<br />
<br />
Special prompts can alter that rhythm. Some disable experience-writing for a turn. Others allow the vampire's name to change, permit the editing of old experiences, reduce or increase permanent memory capacity, or end the chronicle entirely with an epilogue. TYOV-Web exposes these rules clearly during play, but the rules never overwhelm the fiction. They exist to sharpen it.<br />
<br />
== An Example Unlife: Karmis ==<br />
<br />
The most compelling way to understand the application is through one of its stored characters. One campaign in the database follows '''Karmis''', formerly '''Ekurzu''' and before that '''Naram''', across roughly three and a half thousand years.<br />
<br />
He begins in Bronze Age Mari as a temple scribe: precise, observant, and deeply embedded in the religious and political machinery of the city. His mortal life is defined by clay tablets, whispered intelligence, and courtly danger. He falls in love with Hessa, is shaped by the mentorship of the high priest Ibbi-Zamri, and is eventually turned by the ancient vampire Ashurban the Veiled. In one of the campaign's defining cruelties, Ibbi-Zamri becomes the first person Karmis kills after the turning.<br />
<br />
The early centuries of his unlife are marked by exile and shame. He flees with Ennatum, struggles to master the hunger, tries to imagine restraint as redemption, and fails. One of the campaign's most effective lines comes from this period: he builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually he devours Ennatum during a sandstorm and carries that loss into the long middle stretch of the story.<br />
<br />
From there the campaign moves through one civilisation after another. Karmis passes through Akhenaten's Egypt, the imperial roads of the Achaemenids, the scholarly world of Alexandria, Roman frontiers, monastic Europe, Mediterranean trade routes, and the violence of the early modern Atlantic world. His roles change less than the world around him does. He remains a scribe, witness, forger, archivist, and careful observer of institutions that never last as long as he does.<br />
<br />
The campaign also shows how the game's systems create character rather than merely recording it. Karmis gains skills such as ''Silent Cartography'', the ability to trace unseen paths of influence, and ''Ash-Tongue'', a talent for insinuation and social survival. But he loses others as time damages his identity. He once knew how to decipher ancient texts; later he no longer can. He once believed he could control the beast within; later even that confidence disappears. The mechanics translate immortality into erosion.<br />
<br />
One of the campaign's richest relationships is with '''Thooni''', a scholar who recognises the name ''Ekurzu'' not as legend but as continuity. After her mortal death, the relationship persists in altered form: a spectral Thooni begins appearing in the margins of Karmis's diary, leaving fragments in languages he can no longer read. TYOV-Web handles this elegantly because its model of a character is not limited to a living cast list. People can be present, absent, lost, remembered, or transformed into symbols the protagonist can no longer fully interpret.<br />
<br />
By the late Roman and early medieval portions of the chronicle, the cost of the memory rules becomes brutal. Karmis loses so many memories that even the event of his own turning is no longer available to him. He relies on diaries and external records to stabilise himself, yet those too are vulnerable. A carved chamber called ''The Walls of Forgetting'' and a later monastery diary both disappear. The application does not treat this as simple inventory loss; it feels instead like a second death for pieces of the self.<br />
<br />
In the final act, Karmis witnesses the Atlantic slave trade and begins keeping a ledger of names drawn from shipping manifests and punishment records. A later response captures the moral exhaustion of the character with unusual sharpness: he no longer imagines himself purified by restraint, only redirected by purpose. He feeds on slavers and calls it justice, yet recognises that the blood tastes the same. This is the kind of line the application is built to preserve: not just event logs, but accumulations of ethical fatigue.<br />
<br />
His last great companion is '''Mirelde of Bracha''', who becomes mirror, partner, and eventually historian. By the time the epilogue arrives, the story is no longer told in Karmis's own voice. Mirelde writes the closing judgment on him: not as a monster laid to rest, but as "just a man who remembered too much, for too long, and chose, in the end, peace." That shift in narrator is exactly the sort of late-game turn TYOV-Web makes easy to sustain, because it keeps the campaign legible even after the protagonist himself has become unreliable.<br />
<br />
== Why the Application Works ==<br />
<br />
What makes TYOV-Web effective is not that it digitises every rule, though it largely does. Its strength is that it understands which parts of the original game are dramatically important and places those at the centre of the interface.<br />
<br />
The main play screen is organised around the prompt, the character sheet, and the memory display. The prompt is always the immediate literary provocation. The memory display constantly reminds the player of pressure and loss: active memories, diary memories, and forgotten memories sit in visible relation to one another. Skills, resources, marks, and known characters are editable in place, which means the character sheet grows and collapses alongside the fiction instead of feeling like a separate administrative surface.<br />
<br />
The result is a frontend that behaves less like a dashboard and more like a writing desk. Players move between the prompt text, the experience form, and the fragments of the vampire's surviving life. Even when the application is doing something purely mechanical, such as validating whether the player may continue, the effect is narrative: it is asking whether the current moment of the story has been fully accounted for.<br />
<br />
== The Frontend as Chronicle ==<br />
<br />
The client side of TYOV-Web is a '''Vue 3''' single-page application written in '''TypeScript'''. In practical terms, this means the entire experience unfolds without page reloads; in literary terms, it allows the game to feel continuous. The player logs in, sees a home screen of active and archived characters, enters a creation wizard for new vampires, and then spends most of the campaign inside a single evolving game view.<br />
<br />
That view is supported by a set of focused screens: a login page, a home dashboard, the six-step character creation flow, the main game interface, an ending screen for completed chronicles, an archive view, and a story view that presents the campaign as a timeline. Around those are a collection of smaller windows and dialogs for editing characters, skills, resources, memories, and experiences. These are important not because there are many of them, but because they preserve the sense that a campaign is always open to revision, annotation, and reinterpretation.<br />
<br />
State is held in Pinia stores for authentication, gameplay, character creation, and theme. That is an implementation detail, but in this case it serves a visible purpose: it keeps the player's character, current prompt, pending changes, and validation state coherent at all times. The interface never feels as if it has forgotten where the player is in the life of the vampire.<br />
<br />
== The Backend as Memory Keeper ==<br />
<br />
Behind the interface is a '''Django 5''' application with a REST API built on '''Django REST Framework'''. The backend models the campaign in the same terms the game itself cares about: '''Character''', '''Memory''', '''Experience''', '''Skill''', '''Resource''', '''Mark''', '''GameCharacter''', '''Prompt''', and '''PendingChange'''. This is not especially glamorous architecture, but it is disciplined. The data model is close to the language of play, which makes the whole system easier to reason about.<br />
<br />
The most interesting design choice is the use of '''pending changes'''. TYOV-Web does not immediately finalise every action the player takes. Instead, new experiences and character-sheet adjustments can accumulate as provisional edits until the player chooses to continue the story. Only then are they committed atomically. This makes the system feel less like a CRUD application and more like a drafting process. A turn can be assembled, reconsidered, and only then sealed into the chronicle.<br />
<br />
Authentication is handled by JWT tokens, and character data is scoped to the authenticated user. The backend exposes endpoints for the game state itself, dice rolling, story continuation, and CRUD operations on memories, experiences, skills, resources, marks, and known characters. In the article, however, the important point is not the shape of the URLs. It is that the backend has been designed to support a narrative workflow rather than a generic records system.<br />
<br />
== Audit Trail ==<br />
<br />
One of the application's strongest features is its audit trail. Each time the player advances to a new prompt, TYOV-Web captures a complete snapshot of the game state: prompt transition, dice roll, character sheet, memories, and the set of changes applied on that turn. In effect, the application keeps both the ''current'' vampire and the ''history of how that vampire became current''.<br />
<br />
This matters for more than debugging. In a game built around forgetting, a turn-by-turn archive becomes part of the theme. The player may choose to lose a memory inside the fiction, but the application still preserves the fact that the loss occurred. The vampire forgets; the chronicle does not.<br />
<br />
== Development and Deployment ==<br />
<br />
TYOV-Web is developed as a two-part web project: Django on the server side, Vue on the client side. In local development the repository can be started with a PowerShell bootstrap script, which creates the Python environment, installs dependencies, runs migrations, and launches both servers. In production, the frontend is built with Vite and the backend is configured through the usual Django environment settings, including a production mode selected with <code>DJANGO_ENV=production</code>.<br />
<br />
Testing exists on both sides of the stack. The backend is covered with '''pytest''' and '''pytest-django'''; the frontend uses '''Playwright''' for end-to-end coverage of the creation flow and core game loop. Those details are reassuring, but secondary. The more meaningful point is that the project has been built as an actual maintained application rather than a one-off prototype.<br />
<br />
== Reception Within the Project ==<br />
<br />
As a fan-made implementation, TYOV-Web is best understood as an act of interpretation. It does not try to replace the tabletop experience with spectacle. Instead it asks what a web application can do well for this particular game: preserve long-form writing, reduce clerical overhead, make memory pressure visible, and retain the full history of a life that the protagonist can no longer fully remember. In that sense it is not merely a helper app. It is a machine for turning play into biography.<br />
<br />
== See Also ==<br />
<br />
* ''Thousand Year Old Vampire'' by Tim Hutchings<br />
* [[Django (web framework)]]<br />
* [[Vue.js]]<br />
* [[Single-page application]]<br />
<br />
== References ==<br />
<br />
{{Reflist}}<br />
<br />
[[Category:Web applications]]<br />
[[Category:Role-playing video games]]<br />
[[Category:Django (web framework) applications]]<br />
[[Category:Vue.js applications]]<br />
[[Category:Solo role-playing games]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Thousand_Year_Old_Vampire&diff=389Thousand Year Old Vampire2026-04-12T11:26:18Z<p>Mvuijlst: /* A Life in Summary */</p>
<hr />
<div>{{Infobox <br />
| 01_name = Thousand Year Old Vampire – Web Helper<br />
| 02_logo =<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_programming language = Python (Django 5), TypeScript (Vue 3)<br />
| 05_operating system = Cross-platform (Web)<br />
| 06_genre = Solo RPG Digital Companion<br />
| 07_license = custom<br />
| 08_website = <code>https://tyov.yusupov.cloud</code><br />
}}<br />
<br />
'''Thousand Year Old Vampire – Web Helper''' ('''TYOV-Web''') is a modern web-based implementation of the solo tabletop role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. The application digitises the game's complex mechanics of memory, experience, and character development, allowing players to create and guide a vampire character across centuries of unlife through an interactive browser interface. The backend is built with '''Django 5''' and '''Django REST Framework'''; the frontend is a '''Vue 3''' single-page application.<br />
<br />
== Overview ==<br />
<br />
''Thousand Year Old Vampire'' is a solo storytelling RPG in which a player creates a vampire character and guides it through an increasingly fragmented existence spanning hundreds or thousands of years. The central tension lies in the vampire's deteriorating memory: as an immortal being it accumulates experiences, but its ancient mind can only retain a limited number of memories at any time. Players must constantly choose what to remember and what to forget.<br />
<br />
TYOV-Web fully implements the game's rules—character creation, dice-driven prompt navigation, memory management, diary storage, skills, resources, marks, known characters, and game-ending conditions—in a reactive web interface with persistent server-side storage and a complete audit trail.<br />
<br />
== Game Rules ==<br />
<br />
=== Core Concept ===<br />
<br />
The player creates a vampire and progresses through numbered '''prompts''' (story scenarios). Each prompt asks the player to narrate what happens to the vampire during a particular era. The game is non-linear: dice rolls determine which prompt to visit next, and most prompts have multiple '''variations''' (A, B, C) to prevent repetition.<br />
<br />
=== Character Creation ===<br />
<br />
Character creation follows a guided six-step wizard:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Step !! Description<br />
|-<br />
| 1. Mortal Life || Establish the vampire's name, background, and mortal existence<br />
|-<br />
| 2. Mortal Characters || Define 2–4 NPCs from the vampire's human life (friends, mentors, rivals, lovers)<br />
|-<br />
| 3. Skills || Choose 2–3 starting skills representing mortal expertise<br />
|-<br />
| 4. Resources || Select initial possessions and locations<br />
|-<br />
| 5. Combination Experience || Write a pivotal mortal-life experience that ties characters, skills, and resources together<br />
|-<br />
| 6. The Turning || Narrate how and why the character was turned into a vampire<br />
|}<br />
<br />
=== Memory System ===<br />
<br />
The memory system is the heart of the game:<br />
<br />
* A character may hold a maximum of '''5 active memories''' (adjustable by prompt rules and permanent effects).<br />
* Each memory can contain up to '''3 experiences''' (individual narrative entries).<br />
* When the limit is exceeded, the player must '''forget''' (permanently lose) a memory, or '''move''' one to a '''diary''' (if the character possesses one).<br />
* A '''diary''' is a special resource that stores up to '''4 additional memories''' outside the active limit.<br />
* If the diary resource is lost, all memories stored in it are also lost.<br />
* Some prompts grant or remove permanent memory slots (<code>memory_slot_gain</code>, <code>memory_slot_loss</code>).<br />
<br />
=== Dice Rolling and Prompt Navigation ===<br />
<br />
Each turn the player rolls two dice:<br />
<br />
* '''D10''' (1–10) minus '''D6''' (1–6) = result (range: −5 to +9).<br />
* A '''positive''' result moves forward that many prompts.<br />
* A '''negative''' result moves backward.<br />
* A result of '''zero''' stays at the current prompt number but selects the next unused variation.<br />
<br />
Variations are visited in order A → B → C. If all variations of a prompt have been used, the system finds the next available variation in prompt order.<br />
<br />
=== Turn Structure ===<br />
<br />
Each game turn follows this sequence:<br />
<br />
# '''Prompt Presentation''' – The current prompt text and any special rules are displayed.<br />
# '''Dice Roll''' – The player rolls D10 − D6 to determine the next prompt.<br />
# '''Experience Creation''' – The player writes at least one narrative experience for the current prompt.<br />
# '''Character Updates''' – Skills, resources, marks, and known characters may be added, edited, checked, or removed.<br />
# '''Memory Management''' – The player resolves any memory overflow (forget or move to diary).<br />
# '''Validation''' – The system verifies all rules are satisfied (at least one experience added, memory limits respected, etc.).<br />
# '''Continue''' – All pending changes are atomically committed and the game advances to the next prompt.<br />
<br />
=== Character Attributes ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Attribute !! Description<br />
|-<br />
| '''Skills''' || Learned abilities; can be ''normal'' (latent), ''checked'' (used/active), or ''lost'' (permanently removed).<br />
|-<br />
| '''Resources''' || Possessions or locations; typed as ''portable'' or ''stationary''. One resource may be flagged as a ''diary''.<br />
|-<br />
| '''Marks''' || Physical or psychological scars that accumulate over time.<br />
|-<br />
| '''Known Characters''' || NPCs the vampire has encountered; typed as ''mortal'' or ''immortal''; may be lost (dead, vanished, etc.).<br />
|}<br />
<br />
=== Special Prompt Rules ===<br />
<br />
Certain prompts carry special mechanics encoded as rules:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Rule !! Effect<br />
|-<br />
| <code>no_experience</code> || Experience creation is disabled for this turn<br />
|-<br />
| <code>allow_name_change</code> || The player may change the vampire's name<br />
|-<br />
| <code>memory_modification</code> || The player may edit the text of existing experiences<br />
|-<br />
| <code>memory_slot_loss</code> || Permanent reduction of memory capacity by 1<br />
|-<br />
| <code>memory_slot_gain</code> || Permanent increase of memory capacity by 1<br />
|-<br />
| <code>game_over</code> || The game ends; the player writes an epilogue<br />
|}<br />
<br />
=== Game Ending ===<br />
<br />
The game ends when the player reaches a prompt with the <code>game_over</code> rule (or under other conditions defined by the original game). The player writes an '''epilogue'''—a final reflection on the vampire's story—and the character is archived. A statistics summary shows prompt count, memories, experiences, skills, resources, marks, and characters accumulated during the playthrough.<br />
<br />
== Architecture ==<br />
<br />
=== Technology Stack ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Layer !! Technology !! Version<br />
|-<br />
| Backend framework || Django || 5.0.6<br />
|-<br />
| REST API || Django REST Framework || 3.15.1<br />
|-<br />
| Authentication || Simple JWT (custom) || 5.3.0<br />
|-<br />
| CORS || django-cors-headers || 4.3.1<br />
|-<br />
| Image handling || Pillow || 11.3.0<br />
|-<br />
| Production server || Gunicorn || 21.2.0<br />
|-<br />
| Frontend framework || Vue.js || 3.5<br />
|-<br />
| State management || Pinia || 3.0<br />
|-<br />
| Routing || Vue Router || 4.5<br />
|-<br />
| HTTP client || Axios || 1.10<br />
|-<br />
| CSS framework || Bootstrap || 5.3<br />
|-<br />
| Build tool || Vite || 7.0<br />
|-<br />
| Language || TypeScript || 5.8<br />
|-<br />
| Testing (backend) || pytest + pytest-django || 8.0 / 4.8<br />
|-<br />
| Testing (frontend) || Playwright || 1.53<br />
|}<br />
<br />
=== High-Level Diagram ===<br />
<br />
<pre><br />
┌─────────────────────────────────────────────────┐<br />
│ Vue 3 SPA (TypeScript) │<br />
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│<br />
│ │ Views │ │Components│ │ Pinia Stores ││<br />
│ │ (7 pages)│ │ (14+) │ │ auth/game/theme/ ││<br />
│ │ │ │ │ │ characterCreation ││<br />
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘│<br />
│ └─────────────┴────────────────┘ │<br />
│ │ Axios │<br />
│ ▼ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django REST API │<br />
│ /api/auth/login /api/auth/verify │<br />
│ /api/characters/ (CRUD + game_state, │<br />
│ roll_dice, continue_story, audit_trail) │<br />
│ /api/characters/<id>/memories/ │<br />
│ /api/characters/<id>/experiences/ │<br />
│ /api/characters/<id>/skills/ │<br />
│ /api/characters/<id>/resources/ │<br />
│ /api/characters/<id>/marks/ │<br />
│ /api/characters/<id>/characters/ │<br />
│ /api/characters/<id>/pending-changes/ │<br />
│ /api/prompts/ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django ORM / SQLite │<br />
│ Character · Memory · Experience · Skill │<br />
│ Resource · Mark · GameCharacter · Prompt │<br />
│ PendingChange · GameStateSnapshot │<br />
└─────────────────────────────────────────────────┘<br />
</pre><br />
<br />
== Backend ==<br />
<br />
=== Django Apps ===<br />
<br />
The project is organised into three Django apps plus a settings module:<br />
<br />
{| class="wikitable"<br />
|-<br />
! App !! Purpose<br />
|-<br />
| <code>vampire</code> || Core domain models: Character, Memory, Experience, Skill, Resource, Mark, GameCharacter, Prompt, PendingChange, GameStateSnapshot<br />
|-<br />
| <code>tyov_api</code> || REST API layer: serialisers, viewsets, URL routing, permissions, middleware<br />
|-<br />
| <code>authentication</code> || JWT-based login and token verification endpoints<br />
|-<br />
| <code>tyov_backend</code> || Django project settings, URL root, WSGI/ASGI configuration<br />
|}<br />
<br />
=== Data Models ===<br />
<br />
==== Character ====<br />
<br />
The central model, owned by a Django <code>User</code> via a ForeignKey:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Field !! Type !! Description<br />
|-<br />
| <code>name</code> || CharField(200) || Current name of the vampire<br />
|-<br />
| <code>description</code> || TextField || Background/appearance description<br />
|-<br />
| <code>image</code> || ImageField || Optional character portrait<br />
|-<br />
| <code>current_prompt</code> || CharField(10) || ID of the current prompt (e.g. "17a")<br />
|-<br />
| <code>last_dice_roll</code> || JSONField || Stores D10, D6, and result of the last roll<br />
|-<br />
| <code>visited_prompts</code> || JSONField(list) || List of all prompt IDs visited in order<br />
|-<br />
| <code>memory_slots_lost</code> || IntegerField || Permanent memory slot reductions<br />
|-<br />
| <code>memory_slots_gained</code> || IntegerField || Permanent memory slot increases<br />
|-<br />
| <code>creation_step</code> || IntegerField(1–6) || Tracks progress through the creation wizard<br />
|-<br />
| <code>is_creation_complete</code> || BooleanField || True when all six creation steps are finished<br />
|-<br />
| <code>creation_data</code> || JSONField || Temporary storage during creation<br />
|-<br />
| <code>epilogue</code> || TextField || Player's final reflection (set at game end)<br />
|-<br />
| <code>is_completed</code> || BooleanField || Whether the story has ended<br />
|-<br />
| <code>completed_at</code> || DateTimeField || Timestamp of story completion<br />
|}<br />
<br />
==== Memory ====<br />
<br />
A memory belongs to a Character and holds up to 3 Experiences:<br />
<br />
* <code>title</code> – descriptive name (unique per character)<br />
* <code>in_diary</code> – whether the memory is stored in the diary<br />
* <code>is_lost</code> – whether the memory has been forgotten<br />
<br />
==== Experience ====<br />
<br />
An individual narrative entry within a Memory:<br />
<br />
* <code>title</code> – optional short description<br />
* <code>content</code> – the narrative text<br />
* <code>prompt_id</code> – which prompt generated this experience<br />
* <code>date_info</code> – temporal context (e.g. "Winter, 431 CE")<br />
<br />
==== Skill ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>status</code> – one of <code>normal</code>, <code>checked</code>, or <code>lost</code><br />
<br />
==== Resource ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>resource_type</code> – <code>portable</code> or <code>stationary</code><br />
* <code>is_diary</code> – flags the special diary resource (constrained to one active diary per character)<br />
* <code>is_lost</code><br />
<br />
==== Mark ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>is_lost</code><br />
<br />
==== GameCharacter ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>character_type</code> – <code>mortal</code> or <code>immortal</code><br />
* <code>relationship</code> – e.g. friend, rival, mentor, love, enemy, neutral<br />
* <code>is_lost</code><br />
<br />
==== Prompt ====<br />
<br />
* <code>prompt_id</code> – e.g. "17a", "32b"<br />
* <code>number</code>, <code>variation</code> – parsed components for sorting<br />
* <code>content</code> – the scenario text<br />
* <code>rules</code> – special mechanics as comma-separated tokens (e.g. <code>no_experience, allow_name_change</code>)<br />
<br />
==== PendingChange ====<br />
<br />
Temporary storage for changes before they are atomically committed on "Continue":<br />
<br />
* <code>change_type</code> – experience, memory, skill, resource, mark, or character<br />
* <code>change_data</code> – JSON payload of the change<br />
<br />
==== GameStateSnapshot (Audit Trail) ====<br />
<br />
Automatically created each turn to record the complete game state:<br />
<br />
* <code>turn_number</code> – sequential, starting from 1<br />
* <code>prompt_id</code> / <code>next_prompt_id</code> – transition<br />
* <code>dice_roll</code> – raw dice data<br />
* <code>game_state</code> – full JSON snapshot of all memories, skills, resources, etc.<br />
* <code>changes_applied</code> – JSON array of pending changes that were committed<br />
* <code>created_at</code> – timestamp<br />
<br />
=== API Endpoints ===<br />
<br />
All endpoints require JWT authentication (except login).<br />
<br />
==== Authentication ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| POST || <code>/api/auth/login/</code> || Authenticate with username/password; returns JWT token<br />
|-<br />
| POST || <code>/api/auth/verify/</code> || Verify current token and return user info<br />
|}<br />
<br />
Login is rate-limited to 5 requests per minute per IP.<br />
<br />
==== Characters ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/characters/</code> || List all characters for the authenticated user<br />
|-<br />
| POST || <code>/api/characters/</code> || Create a new character<br />
|-<br />
| GET || <code>/api/characters/{id}/</code> || Retrieve full character detail (prefetched relations)<br />
|-<br />
| PUT/PATCH || <code>/api/characters/{id}/</code> || Update character fields<br />
|-<br />
| DELETE || <code>/api/characters/{id}/</code> || Delete a character<br />
|-<br />
| GET || <code>/api/characters/{id}/game_state/</code> || Complete game state including prompt, validation, dice info<br />
|-<br />
| POST || <code>/api/characters/{id}/roll_dice/</code> || Roll D10 − D6 and store the result<br />
|-<br />
| POST || <code>/api/characters/{id}/continue_story/</code> || Validate, commit pending changes, advance to next prompt<br />
|-<br />
| GET || <code>/api/characters/{id}/audit_trail/</code> || View turn-by-turn audit history<br />
|-<br />
| GET || <code>/api/characters/{id}/game-state-changes/</code> || Timeline of state changes between turns<br />
|}<br />
<br />
==== Nested Character Resources ====<br />
<br />
For each character, full CRUD is available on:<br />
<br />
* <code>/api/characters/{id}/memories/</code> (plus <code>move_to_diary</code> and <code>restore_lost_memory</code> actions)<br />
* <code>/api/characters/{id}/experiences/</code><br />
* <code>/api/characters/{id}/skills/</code><br />
* <code>/api/characters/{id}/resources/</code><br />
* <code>/api/characters/{id}/marks/</code><br />
* <code>/api/characters/{id}/characters/</code> (known NPCs)<br />
* <code>/api/characters/{id}/pending-changes/</code><br />
<br />
==== Prompts ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/prompts/</code> || List all game prompts<br />
|-<br />
| GET || <code>/api/prompts/{prompt_id}/</code> || Retrieve a single prompt by ID<br />
|}<br />
<br />
=== Permissions and Security ===<br />
<br />
* All character data is scoped to the authenticated user via <code>IsCharacterOwner</code> permission.<br />
* JWT tokens are sent as <code>Authorization: Bearer {token}</code> headers.<br />
* The login endpoint is throttled (5/minute) to prevent brute-force attacks.<br />
* All pending changes are processed inside a database '''transaction''' to guarantee atomicity.<br />
* CORS headers are configured via <code>django-cors-headers</code>.<br />
<br />
== Frontend ==<br />
<br />
=== Views (Pages) ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! View !! Route !! Description<br />
|-<br />
| '''LoginView''' || <code>/login</code> || Authentication form; redirects authenticated users to home<br />
|-<br />
| '''HomeView''' || <code>/</code> || Dashboard showing all active characters in a card grid<br />
|-<br />
| '''CharacterCreationView''' || <code>/character-creation/:id</code> || Six-step creation wizard<br />
|-<br />
| '''GameView''' || <code>/game/:characterId</code> || Main game loop: prompt display, experience form, dice rolling, entity management, memory display<br />
|-<br />
| '''GameEndedView''' || <code>/game/:characterId/ended</code> || End-of-story screen with statistics and epilogue<br />
|-<br />
| '''RecordsView''' || <code>/records</code> || Archive of current and completed characters<br />
|-<br />
| '''StoryView''' || <code>/story/:characterId</code> || Narrative timeline with experience history, character stats sidebar, and epilogue<br />
|}<br />
<br />
All routes except <code>/login</code> require authentication. The router guard redirects unauthenticated users.<br />
<br />
=== Key Components ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Component !! Purpose<br />
|-<br />
| '''PromptSection''' || Displays the current prompt text, special rules, and dice roll results<br />
|-<br />
| '''ExperienceForm''' || Form for writing new experiences with title, date, content, and memory selection<br />
|-<br />
| '''MemoriesDisplay''' || Shows active, diary, and lost memories with experience counts; includes move-to-diary, delete, and restore actions<br />
|-<br />
| '''GameDataSection''' || Reusable list for skills, resources, or marks with add/edit/delete controls<br />
|-<br />
| '''CharactersSection''' || Grid of known NPCs with type badges and edit/delete<br />
|-<br />
| '''EntityCreationWindow''' || Draggable modal for creating/editing skills, resources, marks<br />
|-<br />
| '''CharacterCreationWindow''' || Draggable modal for creating/editing NPC characters<br />
|-<br />
| '''ExperienceEditWindow''' || Window for editing existing experience text<br />
|-<br />
| '''DiaryCreationModal''' || Modal for creating a diary resource and moving a memory into it<br />
|-<br />
| '''ConfirmationDialog''' || Generic confirmation dialog for destructive actions<br />
|-<br />
| '''ValidationWarning''' || Displays validation errors when game rules are not satisfied<br />
|}<br />
<br />
=== State Management (Pinia) ===<br />
<br />
Four Pinia stores manage application state:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Store !! Responsibility<br />
|-<br />
| '''auth''' || JWT token, user object, login/logout, token expiry handling<br />
|-<br />
| '''game''' || Characters list, current character, game state, all CRUD actions for entities, dice rolling, story continuation<br />
|-<br />
| '''characterCreation''' || Multi-step wizard data, initial character creation<br />
|-<br />
| '''theme''' || Dark/light mode toggle with localStorage persistence<br />
|}<br />
<br />
=== API Service Layer ===<br />
<br />
* '''<code>api.ts</code>''' – Axios instance with base URL auto-detection (development vs. production), request interceptor for JWT headers, response interceptor for 401/token-expiry handling.<br />
* '''<code>gameService.ts</code>''' – All API call methods: authentication, character CRUD, dice rolling, story continuation, memory/experience/skill/resource/mark/character management.<br />
* '''<code>entityService.ts</code>''' – Generic <code>EntityService</code> class instantiated for skills, resources, marks, and characters for DRY CRUD operations.<br />
<br />
=== Composables ===<br />
<br />
Vue composables encapsulate reusable business logic:<br />
<br />
* '''<code>useGameData()</code>''' – Computed properties derived from the game store (current character, memories, skills, resources, etc.)<br />
* '''<code>useExperienceForm()</code>''' – Form state, validation, memory selection, and reset logic<br />
* '''<code>useEntityManagement()</code>''' – Generic CRUD operations with optional confirmation dialogs<br />
* '''<code>useSkillManagement()</code>''', '''<code>useResourceManagement()</code>''', '''<code>useMarkManagement()</code>''', '''<code>useMemoryManagement()</code>''' – Specialised wrappers<br />
* '''<code>useConfirmationDialog()</code>''' – Promise-based modal confirmation<br />
* '''<code>useMemoryDisplay()</code>''' – Display logic for memories including pending-change awareness<br />
* '''<code>useExperienceDisplay()</code>''' – Markdown rendering for experience content<br />
* '''<code>usePendingChangesDisplay()</code>''' – Badge rendering for undo-able pending changes<br />
<br />
== Audit Trail ==<br />
<br />
The application includes an automatic audit trail that captures the complete game state every time the player advances to a new prompt.<br />
<br />
Each '''GameStateSnapshot''' records:<br />
<br />
* The turn number (sequential from 1)<br />
* The prompt transition (e.g. 36a → 34a)<br />
* The dice roll<br />
* A complete JSON snapshot of all memories, skills, resources, marks, and known characters<br />
* All pending changes that were committed<br />
<br />
The audit trail is accessible via:<br />
<br />
* '''API''': <code>GET /api/characters/{id}/audit_trail/</code> with optional <code>?turn=N</code> and <code>?limit=N</code> parameters<br />
* '''Management command''': <code>python manage.py view_audit_trail {id} [--summary] [--turn N] [--export file.json]</code><br />
* '''Timeline API''': <code>GET /api/characters/{id}/game-state-changes/</code> for a structured timeline of all state changes<br />
<br />
== Deployment ==<br />
<br />
=== Local Development ===<br />
<br />
<pre><br />
.\startup.ps1<br />
</pre><br />
<br />
This script creates a virtual environment, installs dependencies, runs migrations, and starts both the Django backend (<code>http://localhost:8000</code>) and the Vue dev server (<code>http://localhost:5173</code>).<br />
<br />
=== Production ===<br />
<br />
* Set <code>DJANGO_ENV=production</code><br />
* Build the frontend: <code>cd frontend && npm run build</code><br />
* Serve with Gunicorn behind a reverse proxy<br />
* Static files are collected into the <code>static/</code> directory<br />
* The production frontend points to <code>https://tyov.yusupov.cloud</code><br />
<br />
== Example: A Finished Character ==<br />
<br />
The following is an example of a character from an actual playthrough stored in the application database. It demonstrates how the game's mechanics play out over an extended narrative.<br />
<br />
=== Karmiš (formerly Ekurzu / Naram) ===<br />
<br />
'''Description:''' Naram was a temple scribe in the ancient city of Mari: meticulous, observant, and deeply entangled in the political and spiritual life of the city. His life was shaped by clay tablets, omens, and whispered secrets carried through palace corridors and temple courtyards. Behind his calm demeanor lies a mind constantly at work—recording, interpreting, and surviving.<br />
<br />
'''Prompts visited:''' 34 prompts across variations, including: 1a, 4a, 11a–c, 12a, 17a, 20a, 24a, 25a, 32a–b, 34a–36a, 37a–41c, 43a–c, 47a, 52a, 57a, 64a, 66a, 68a, 71a, 73a.<br />
<br />
'''Final prompt:''' 73a<br />
<br />
'''Memory slots lost:''' 1 · '''Memory slots gained:''' 1 (net effect: standard 5-memory limit)<br />
<br />
==== Epilogue ====<br />
<br />
<blockquote><br />
He has not died. Let me say that plainly. There will be no grave. He is alive, but quietly, deliberately, and utterly outside your reach.<br />
<br />
When I first met him, I did not understand what he was. He wore his years like dust on old vellum—thin, barely visible, but ever present. [...] Over time, I became his mirror, then his partner, and finally his historian.<br />
<br />
But someone has to begin the telling. Someone has to place the first stone. So this book begins in a house of quiet gardens and low ceilings, where he writes in the mornings and feeds only when he must. [...]<br />
<br />
Just a man who remembered too much, for too long. And chose, in the end, peace.<br />
<br />
— ''Mirelde''<br />
</blockquote><br />
<br />
==== A Life in Summary ====<br />
<br />
Karmiš's story spans roughly three and a half thousand years. It begins in Bronze Age Mesopotamia, where the mortal scribe Naram serves in the temple of Ishtar at Mari. He writes omens, navigatesg palace intrigue, and fals in love with a woman named Hessa who moves through the court "like smoke." His mentor, the High Priest Ibbi-Zamri, is the first person he kills after being turned by the ancient vampire Ashurban the Veiled.<br />
<br />
The early centuries are defined by guilt and exile. Fleeing with his mortal companion Ennatum, the newly-made vampire (now calling himself Ekurzu) struggles to control his hunger. He builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually the hunger wins: he devours Ennatum during a sandstorm and spends the following decades alone.<br />
<br />
The middle game carries the character through the great civilisations of antiquity: Amarna under Akhenaten, the Achaemenid Royal Road, the libraries of Alexandria—always in the role of scribe, forger, or quiet observer. He accumulates skills like ''Silent Cartography'' ("I trace the unseen paths between people, places, and power") and ''Ash-Tongue'' ("I speak in soot and suggestion, in the cracks between laws"), but loses others as the centuries erode his identity: the ability to ''Decipher Ancient Texts'' and even ''I Control the Beast'' both slip away.<br />
<br />
A pivotal relationship develops with the scholar Thoöni, who recognises the name ''Ekurzu'' not as myth but as continuity. Later, after Thoöni's mortal death, her spectral echo begins appearing in the margins of his diary, scratching fragments in languages he can no longer read.<br />
<br />
By the late Roman period Karmiš has lost so many memories that he can barely hold a conversation. The game's memory mechanics enforce this viscerally: eight of his sixteen memories were permanently forgotten, including ''The Turning'' itself; the vampire no longer remembers how he was made. He compensates by keeping diaries, but even those are lost: ''The Walls of Forgetting'' (memory carvings in five scripts beneath a shrine near Carchemish) and ''The Monastery Diary'' both vanish, taking their stored memories with them.<br />
<br />
The final act takes place in early modern Europe. Karmiš witnesses the Atlantic slave trade first-hand and begins compiling ''The Margins of Manifest'', a cipher-folio of names taken from shipping manifests and punishment ledgers. His response to prompt 66a captures the shift:<br />
<br />
<blockquote><br />
''It is no longer a question of restraint. That was a younger version of me, one who believed self-control made me different from the others. Now I am different in purpose, not method. I feed from slavers and call it justice, but the blood tastes the same.''<br />
</blockquote><br />
<br />
His companion in the final centuries is Mirelde of Bracha. She is an immortal who becomes his mirror, partner, and ultimately his historian. Together they rediscover a clay tablet bearing his original name in a Venetian bookseller's back room (prompt 68a, 1704 CE), and in a ruined estate outside Smyrna Mirelde finds the remains of a life Karmiš can no longer remember.<br />
<br />
At the story's end Karmiš retains only five active memories, three diary memories, two marks (''The Unblinking Eye'', a scar that burns in the presence of lies and ''The Gesture Forbidden'', an involuntary court gesture mistaken for mockery), and three possessions: his diary ''Kept Against Forgetting'', the clay tablet bearing his name, and the slave-trade folio. Of the eleven characters he encountered, only four remain: Ashurban (his distant maker), Mirelde (his companion), Thoöni's ghost, and a nameless figure known only as ''The One Who Does Not Answer''. Over 34 prompts he accumulated 37 experiences, gained and lost a memory slot each, and burned through three separate diaries.<br />
<br />
The character's story is narrated in the epilogue not by Karmiš himself but by Mirelde, who insists: "He has not died. [...] Just a man who remembered too much, for too long. And chose, in the end, ''peace''."<br />
<br />
== Testing ==<br />
<br />
=== Backend ===<br />
<br />
Tests are run with '''pytest''' and '''pytest-django''':<br />
<br />
<pre><br />
pytest<br />
</pre><br />
<br />
Test files include:<br />
* <code>vampire/test_models.py</code> – model unit tests<br />
* <code>tyov_api/test_api.py</code> – API endpoint integration tests<br />
* <code>tyov_api/test_models.py</code> – API model tests<br />
* <code>authentication/test_views.py</code> – authentication tests<br />
<br />
=== Frontend ===<br />
<br />
End-to-end tests use '''Playwright''':<br />
<br />
<pre><br />
cd frontend<br />
npx playwright test<br />
</pre><br />
<br />
Test specs include:<br />
* <code>e2e/character-creation-workflow.spec.ts</code> – character creation wizard<br />
* <code>e2e/tyov-game.spec.ts</code> – game loop testing<br />
* <code>e2e/vue.spec.ts</code> – general Vue component tests<br />
<br />
== See Also ==<br />
<br />
* ''Thousand Year Old Vampire'' by Tim Hutchings – the original tabletop game<br />
* [[Django (web framework)]]<br />
* [[Vue.js]]<br />
* [[Single-page application]]<br />
<br />
== References ==<br />
<br />
{{Reflist}}<br />
<br />
[[Category:Web applications]]<br />
[[Category:Role-playing video games]]<br />
[[Category:Django (web framework) applications]]<br />
[[Category:Vue.js applications]]<br />
[[Category:Solo role-playing games]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Thousand_Year_Old_Vampire&diff=388Thousand Year Old Vampire2026-04-12T11:22:40Z<p>Mvuijlst: /* Epilogue */</p>
<hr />
<div>{{Infobox <br />
| 01_name = Thousand Year Old Vampire – Web Helper<br />
| 02_logo =<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_programming language = Python (Django 5), TypeScript (Vue 3)<br />
| 05_operating system = Cross-platform (Web)<br />
| 06_genre = Solo RPG Digital Companion<br />
| 07_license = custom<br />
| 08_website = <code>https://tyov.yusupov.cloud</code><br />
}}<br />
<br />
'''Thousand Year Old Vampire – Web Helper''' ('''TYOV-Web''') is a modern web-based implementation of the solo tabletop role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. The application digitises the game's complex mechanics of memory, experience, and character development, allowing players to create and guide a vampire character across centuries of unlife through an interactive browser interface. The backend is built with '''Django 5''' and '''Django REST Framework'''; the frontend is a '''Vue 3''' single-page application.<br />
<br />
== Overview ==<br />
<br />
''Thousand Year Old Vampire'' is a solo storytelling RPG in which a player creates a vampire character and guides it through an increasingly fragmented existence spanning hundreds or thousands of years. The central tension lies in the vampire's deteriorating memory: as an immortal being it accumulates experiences, but its ancient mind can only retain a limited number of memories at any time. Players must constantly choose what to remember and what to forget.<br />
<br />
TYOV-Web fully implements the game's rules—character creation, dice-driven prompt navigation, memory management, diary storage, skills, resources, marks, known characters, and game-ending conditions—in a reactive web interface with persistent server-side storage and a complete audit trail.<br />
<br />
== Game Rules ==<br />
<br />
=== Core Concept ===<br />
<br />
The player creates a vampire and progresses through numbered '''prompts''' (story scenarios). Each prompt asks the player to narrate what happens to the vampire during a particular era. The game is non-linear: dice rolls determine which prompt to visit next, and most prompts have multiple '''variations''' (A, B, C) to prevent repetition.<br />
<br />
=== Character Creation ===<br />
<br />
Character creation follows a guided six-step wizard:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Step !! Description<br />
|-<br />
| 1. Mortal Life || Establish the vampire's name, background, and mortal existence<br />
|-<br />
| 2. Mortal Characters || Define 2–4 NPCs from the vampire's human life (friends, mentors, rivals, lovers)<br />
|-<br />
| 3. Skills || Choose 2–3 starting skills representing mortal expertise<br />
|-<br />
| 4. Resources || Select initial possessions and locations<br />
|-<br />
| 5. Combination Experience || Write a pivotal mortal-life experience that ties characters, skills, and resources together<br />
|-<br />
| 6. The Turning || Narrate how and why the character was turned into a vampire<br />
|}<br />
<br />
=== Memory System ===<br />
<br />
The memory system is the heart of the game:<br />
<br />
* A character may hold a maximum of '''5 active memories''' (adjustable by prompt rules and permanent effects).<br />
* Each memory can contain up to '''3 experiences''' (individual narrative entries).<br />
* When the limit is exceeded, the player must '''forget''' (permanently lose) a memory, or '''move''' one to a '''diary''' (if the character possesses one).<br />
* A '''diary''' is a special resource that stores up to '''4 additional memories''' outside the active limit.<br />
* If the diary resource is lost, all memories stored in it are also lost.<br />
* Some prompts grant or remove permanent memory slots (<code>memory_slot_gain</code>, <code>memory_slot_loss</code>).<br />
<br />
=== Dice Rolling and Prompt Navigation ===<br />
<br />
Each turn the player rolls two dice:<br />
<br />
* '''D10''' (1–10) minus '''D6''' (1–6) = result (range: −5 to +9).<br />
* A '''positive''' result moves forward that many prompts.<br />
* A '''negative''' result moves backward.<br />
* A result of '''zero''' stays at the current prompt number but selects the next unused variation.<br />
<br />
Variations are visited in order A → B → C. If all variations of a prompt have been used, the system finds the next available variation in prompt order.<br />
<br />
=== Turn Structure ===<br />
<br />
Each game turn follows this sequence:<br />
<br />
# '''Prompt Presentation''' – The current prompt text and any special rules are displayed.<br />
# '''Dice Roll''' – The player rolls D10 − D6 to determine the next prompt.<br />
# '''Experience Creation''' – The player writes at least one narrative experience for the current prompt.<br />
# '''Character Updates''' – Skills, resources, marks, and known characters may be added, edited, checked, or removed.<br />
# '''Memory Management''' – The player resolves any memory overflow (forget or move to diary).<br />
# '''Validation''' – The system verifies all rules are satisfied (at least one experience added, memory limits respected, etc.).<br />
# '''Continue''' – All pending changes are atomically committed and the game advances to the next prompt.<br />
<br />
=== Character Attributes ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Attribute !! Description<br />
|-<br />
| '''Skills''' || Learned abilities; can be ''normal'' (latent), ''checked'' (used/active), or ''lost'' (permanently removed).<br />
|-<br />
| '''Resources''' || Possessions or locations; typed as ''portable'' or ''stationary''. One resource may be flagged as a ''diary''.<br />
|-<br />
| '''Marks''' || Physical or psychological scars that accumulate over time.<br />
|-<br />
| '''Known Characters''' || NPCs the vampire has encountered; typed as ''mortal'' or ''immortal''; may be lost (dead, vanished, etc.).<br />
|}<br />
<br />
=== Special Prompt Rules ===<br />
<br />
Certain prompts carry special mechanics encoded as rules:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Rule !! Effect<br />
|-<br />
| <code>no_experience</code> || Experience creation is disabled for this turn<br />
|-<br />
| <code>allow_name_change</code> || The player may change the vampire's name<br />
|-<br />
| <code>memory_modification</code> || The player may edit the text of existing experiences<br />
|-<br />
| <code>memory_slot_loss</code> || Permanent reduction of memory capacity by 1<br />
|-<br />
| <code>memory_slot_gain</code> || Permanent increase of memory capacity by 1<br />
|-<br />
| <code>game_over</code> || The game ends; the player writes an epilogue<br />
|}<br />
<br />
=== Game Ending ===<br />
<br />
The game ends when the player reaches a prompt with the <code>game_over</code> rule (or under other conditions defined by the original game). The player writes an '''epilogue'''—a final reflection on the vampire's story—and the character is archived. A statistics summary shows prompt count, memories, experiences, skills, resources, marks, and characters accumulated during the playthrough.<br />
<br />
== Architecture ==<br />
<br />
=== Technology Stack ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Layer !! Technology !! Version<br />
|-<br />
| Backend framework || Django || 5.0.6<br />
|-<br />
| REST API || Django REST Framework || 3.15.1<br />
|-<br />
| Authentication || Simple JWT (custom) || 5.3.0<br />
|-<br />
| CORS || django-cors-headers || 4.3.1<br />
|-<br />
| Image handling || Pillow || 11.3.0<br />
|-<br />
| Production server || Gunicorn || 21.2.0<br />
|-<br />
| Frontend framework || Vue.js || 3.5<br />
|-<br />
| State management || Pinia || 3.0<br />
|-<br />
| Routing || Vue Router || 4.5<br />
|-<br />
| HTTP client || Axios || 1.10<br />
|-<br />
| CSS framework || Bootstrap || 5.3<br />
|-<br />
| Build tool || Vite || 7.0<br />
|-<br />
| Language || TypeScript || 5.8<br />
|-<br />
| Testing (backend) || pytest + pytest-django || 8.0 / 4.8<br />
|-<br />
| Testing (frontend) || Playwright || 1.53<br />
|}<br />
<br />
=== High-Level Diagram ===<br />
<br />
<pre><br />
┌─────────────────────────────────────────────────┐<br />
│ Vue 3 SPA (TypeScript) │<br />
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│<br />
│ │ Views │ │Components│ │ Pinia Stores ││<br />
│ │ (7 pages)│ │ (14+) │ │ auth/game/theme/ ││<br />
│ │ │ │ │ │ characterCreation ││<br />
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘│<br />
│ └─────────────┴────────────────┘ │<br />
│ │ Axios │<br />
│ ▼ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django REST API │<br />
│ /api/auth/login /api/auth/verify │<br />
│ /api/characters/ (CRUD + game_state, │<br />
│ roll_dice, continue_story, audit_trail) │<br />
│ /api/characters/<id>/memories/ │<br />
│ /api/characters/<id>/experiences/ │<br />
│ /api/characters/<id>/skills/ │<br />
│ /api/characters/<id>/resources/ │<br />
│ /api/characters/<id>/marks/ │<br />
│ /api/characters/<id>/characters/ │<br />
│ /api/characters/<id>/pending-changes/ │<br />
│ /api/prompts/ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django ORM / SQLite │<br />
│ Character · Memory · Experience · Skill │<br />
│ Resource · Mark · GameCharacter · Prompt │<br />
│ PendingChange · GameStateSnapshot │<br />
└─────────────────────────────────────────────────┘<br />
</pre><br />
<br />
== Backend ==<br />
<br />
=== Django Apps ===<br />
<br />
The project is organised into three Django apps plus a settings module:<br />
<br />
{| class="wikitable"<br />
|-<br />
! App !! Purpose<br />
|-<br />
| <code>vampire</code> || Core domain models: Character, Memory, Experience, Skill, Resource, Mark, GameCharacter, Prompt, PendingChange, GameStateSnapshot<br />
|-<br />
| <code>tyov_api</code> || REST API layer: serialisers, viewsets, URL routing, permissions, middleware<br />
|-<br />
| <code>authentication</code> || JWT-based login and token verification endpoints<br />
|-<br />
| <code>tyov_backend</code> || Django project settings, URL root, WSGI/ASGI configuration<br />
|}<br />
<br />
=== Data Models ===<br />
<br />
==== Character ====<br />
<br />
The central model, owned by a Django <code>User</code> via a ForeignKey:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Field !! Type !! Description<br />
|-<br />
| <code>name</code> || CharField(200) || Current name of the vampire<br />
|-<br />
| <code>description</code> || TextField || Background/appearance description<br />
|-<br />
| <code>image</code> || ImageField || Optional character portrait<br />
|-<br />
| <code>current_prompt</code> || CharField(10) || ID of the current prompt (e.g. "17a")<br />
|-<br />
| <code>last_dice_roll</code> || JSONField || Stores D10, D6, and result of the last roll<br />
|-<br />
| <code>visited_prompts</code> || JSONField(list) || List of all prompt IDs visited in order<br />
|-<br />
| <code>memory_slots_lost</code> || IntegerField || Permanent memory slot reductions<br />
|-<br />
| <code>memory_slots_gained</code> || IntegerField || Permanent memory slot increases<br />
|-<br />
| <code>creation_step</code> || IntegerField(1–6) || Tracks progress through the creation wizard<br />
|-<br />
| <code>is_creation_complete</code> || BooleanField || True when all six creation steps are finished<br />
|-<br />
| <code>creation_data</code> || JSONField || Temporary storage during creation<br />
|-<br />
| <code>epilogue</code> || TextField || Player's final reflection (set at game end)<br />
|-<br />
| <code>is_completed</code> || BooleanField || Whether the story has ended<br />
|-<br />
| <code>completed_at</code> || DateTimeField || Timestamp of story completion<br />
|}<br />
<br />
==== Memory ====<br />
<br />
A memory belongs to a Character and holds up to 3 Experiences:<br />
<br />
* <code>title</code> – descriptive name (unique per character)<br />
* <code>in_diary</code> – whether the memory is stored in the diary<br />
* <code>is_lost</code> – whether the memory has been forgotten<br />
<br />
==== Experience ====<br />
<br />
An individual narrative entry within a Memory:<br />
<br />
* <code>title</code> – optional short description<br />
* <code>content</code> – the narrative text<br />
* <code>prompt_id</code> – which prompt generated this experience<br />
* <code>date_info</code> – temporal context (e.g. "Winter, 431 CE")<br />
<br />
==== Skill ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>status</code> – one of <code>normal</code>, <code>checked</code>, or <code>lost</code><br />
<br />
==== Resource ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>resource_type</code> – <code>portable</code> or <code>stationary</code><br />
* <code>is_diary</code> – flags the special diary resource (constrained to one active diary per character)<br />
* <code>is_lost</code><br />
<br />
==== Mark ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>is_lost</code><br />
<br />
==== GameCharacter ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>character_type</code> – <code>mortal</code> or <code>immortal</code><br />
* <code>relationship</code> – e.g. friend, rival, mentor, love, enemy, neutral<br />
* <code>is_lost</code><br />
<br />
==== Prompt ====<br />
<br />
* <code>prompt_id</code> – e.g. "17a", "32b"<br />
* <code>number</code>, <code>variation</code> – parsed components for sorting<br />
* <code>content</code> – the scenario text<br />
* <code>rules</code> – special mechanics as comma-separated tokens (e.g. <code>no_experience, allow_name_change</code>)<br />
<br />
==== PendingChange ====<br />
<br />
Temporary storage for changes before they are atomically committed on "Continue":<br />
<br />
* <code>change_type</code> – experience, memory, skill, resource, mark, or character<br />
* <code>change_data</code> – JSON payload of the change<br />
<br />
==== GameStateSnapshot (Audit Trail) ====<br />
<br />
Automatically created each turn to record the complete game state:<br />
<br />
* <code>turn_number</code> – sequential, starting from 1<br />
* <code>prompt_id</code> / <code>next_prompt_id</code> – transition<br />
* <code>dice_roll</code> – raw dice data<br />
* <code>game_state</code> – full JSON snapshot of all memories, skills, resources, etc.<br />
* <code>changes_applied</code> – JSON array of pending changes that were committed<br />
* <code>created_at</code> – timestamp<br />
<br />
=== API Endpoints ===<br />
<br />
All endpoints require JWT authentication (except login).<br />
<br />
==== Authentication ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| POST || <code>/api/auth/login/</code> || Authenticate with username/password; returns JWT token<br />
|-<br />
| POST || <code>/api/auth/verify/</code> || Verify current token and return user info<br />
|}<br />
<br />
Login is rate-limited to 5 requests per minute per IP.<br />
<br />
==== Characters ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/characters/</code> || List all characters for the authenticated user<br />
|-<br />
| POST || <code>/api/characters/</code> || Create a new character<br />
|-<br />
| GET || <code>/api/characters/{id}/</code> || Retrieve full character detail (prefetched relations)<br />
|-<br />
| PUT/PATCH || <code>/api/characters/{id}/</code> || Update character fields<br />
|-<br />
| DELETE || <code>/api/characters/{id}/</code> || Delete a character<br />
|-<br />
| GET || <code>/api/characters/{id}/game_state/</code> || Complete game state including prompt, validation, dice info<br />
|-<br />
| POST || <code>/api/characters/{id}/roll_dice/</code> || Roll D10 − D6 and store the result<br />
|-<br />
| POST || <code>/api/characters/{id}/continue_story/</code> || Validate, commit pending changes, advance to next prompt<br />
|-<br />
| GET || <code>/api/characters/{id}/audit_trail/</code> || View turn-by-turn audit history<br />
|-<br />
| GET || <code>/api/characters/{id}/game-state-changes/</code> || Timeline of state changes between turns<br />
|}<br />
<br />
==== Nested Character Resources ====<br />
<br />
For each character, full CRUD is available on:<br />
<br />
* <code>/api/characters/{id}/memories/</code> (plus <code>move_to_diary</code> and <code>restore_lost_memory</code> actions)<br />
* <code>/api/characters/{id}/experiences/</code><br />
* <code>/api/characters/{id}/skills/</code><br />
* <code>/api/characters/{id}/resources/</code><br />
* <code>/api/characters/{id}/marks/</code><br />
* <code>/api/characters/{id}/characters/</code> (known NPCs)<br />
* <code>/api/characters/{id}/pending-changes/</code><br />
<br />
==== Prompts ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/prompts/</code> || List all game prompts<br />
|-<br />
| GET || <code>/api/prompts/{prompt_id}/</code> || Retrieve a single prompt by ID<br />
|}<br />
<br />
=== Permissions and Security ===<br />
<br />
* All character data is scoped to the authenticated user via <code>IsCharacterOwner</code> permission.<br />
* JWT tokens are sent as <code>Authorization: Bearer {token}</code> headers.<br />
* The login endpoint is throttled (5/minute) to prevent brute-force attacks.<br />
* All pending changes are processed inside a database '''transaction''' to guarantee atomicity.<br />
* CORS headers are configured via <code>django-cors-headers</code>.<br />
<br />
== Frontend ==<br />
<br />
=== Views (Pages) ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! View !! Route !! Description<br />
|-<br />
| '''LoginView''' || <code>/login</code> || Authentication form; redirects authenticated users to home<br />
|-<br />
| '''HomeView''' || <code>/</code> || Dashboard showing all active characters in a card grid<br />
|-<br />
| '''CharacterCreationView''' || <code>/character-creation/:id</code> || Six-step creation wizard<br />
|-<br />
| '''GameView''' || <code>/game/:characterId</code> || Main game loop: prompt display, experience form, dice rolling, entity management, memory display<br />
|-<br />
| '''GameEndedView''' || <code>/game/:characterId/ended</code> || End-of-story screen with statistics and epilogue<br />
|-<br />
| '''RecordsView''' || <code>/records</code> || Archive of current and completed characters<br />
|-<br />
| '''StoryView''' || <code>/story/:characterId</code> || Narrative timeline with experience history, character stats sidebar, and epilogue<br />
|}<br />
<br />
All routes except <code>/login</code> require authentication. The router guard redirects unauthenticated users.<br />
<br />
=== Key Components ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Component !! Purpose<br />
|-<br />
| '''PromptSection''' || Displays the current prompt text, special rules, and dice roll results<br />
|-<br />
| '''ExperienceForm''' || Form for writing new experiences with title, date, content, and memory selection<br />
|-<br />
| '''MemoriesDisplay''' || Shows active, diary, and lost memories with experience counts; includes move-to-diary, delete, and restore actions<br />
|-<br />
| '''GameDataSection''' || Reusable list for skills, resources, or marks with add/edit/delete controls<br />
|-<br />
| '''CharactersSection''' || Grid of known NPCs with type badges and edit/delete<br />
|-<br />
| '''EntityCreationWindow''' || Draggable modal for creating/editing skills, resources, marks<br />
|-<br />
| '''CharacterCreationWindow''' || Draggable modal for creating/editing NPC characters<br />
|-<br />
| '''ExperienceEditWindow''' || Window for editing existing experience text<br />
|-<br />
| '''DiaryCreationModal''' || Modal for creating a diary resource and moving a memory into it<br />
|-<br />
| '''ConfirmationDialog''' || Generic confirmation dialog for destructive actions<br />
|-<br />
| '''ValidationWarning''' || Displays validation errors when game rules are not satisfied<br />
|}<br />
<br />
=== State Management (Pinia) ===<br />
<br />
Four Pinia stores manage application state:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Store !! Responsibility<br />
|-<br />
| '''auth''' || JWT token, user object, login/logout, token expiry handling<br />
|-<br />
| '''game''' || Characters list, current character, game state, all CRUD actions for entities, dice rolling, story continuation<br />
|-<br />
| '''characterCreation''' || Multi-step wizard data, initial character creation<br />
|-<br />
| '''theme''' || Dark/light mode toggle with localStorage persistence<br />
|}<br />
<br />
=== API Service Layer ===<br />
<br />
* '''<code>api.ts</code>''' – Axios instance with base URL auto-detection (development vs. production), request interceptor for JWT headers, response interceptor for 401/token-expiry handling.<br />
* '''<code>gameService.ts</code>''' – All API call methods: authentication, character CRUD, dice rolling, story continuation, memory/experience/skill/resource/mark/character management.<br />
* '''<code>entityService.ts</code>''' – Generic <code>EntityService</code> class instantiated for skills, resources, marks, and characters for DRY CRUD operations.<br />
<br />
=== Composables ===<br />
<br />
Vue composables encapsulate reusable business logic:<br />
<br />
* '''<code>useGameData()</code>''' – Computed properties derived from the game store (current character, memories, skills, resources, etc.)<br />
* '''<code>useExperienceForm()</code>''' – Form state, validation, memory selection, and reset logic<br />
* '''<code>useEntityManagement()</code>''' – Generic CRUD operations with optional confirmation dialogs<br />
* '''<code>useSkillManagement()</code>''', '''<code>useResourceManagement()</code>''', '''<code>useMarkManagement()</code>''', '''<code>useMemoryManagement()</code>''' – Specialised wrappers<br />
* '''<code>useConfirmationDialog()</code>''' – Promise-based modal confirmation<br />
* '''<code>useMemoryDisplay()</code>''' – Display logic for memories including pending-change awareness<br />
* '''<code>useExperienceDisplay()</code>''' – Markdown rendering for experience content<br />
* '''<code>usePendingChangesDisplay()</code>''' – Badge rendering for undo-able pending changes<br />
<br />
== Audit Trail ==<br />
<br />
The application includes an automatic audit trail that captures the complete game state every time the player advances to a new prompt.<br />
<br />
Each '''GameStateSnapshot''' records:<br />
<br />
* The turn number (sequential from 1)<br />
* The prompt transition (e.g. 36a → 34a)<br />
* The dice roll<br />
* A complete JSON snapshot of all memories, skills, resources, marks, and known characters<br />
* All pending changes that were committed<br />
<br />
The audit trail is accessible via:<br />
<br />
* '''API''': <code>GET /api/characters/{id}/audit_trail/</code> with optional <code>?turn=N</code> and <code>?limit=N</code> parameters<br />
* '''Management command''': <code>python manage.py view_audit_trail {id} [--summary] [--turn N] [--export file.json]</code><br />
* '''Timeline API''': <code>GET /api/characters/{id}/game-state-changes/</code> for a structured timeline of all state changes<br />
<br />
== Deployment ==<br />
<br />
=== Local Development ===<br />
<br />
<pre><br />
.\startup.ps1<br />
</pre><br />
<br />
This script creates a virtual environment, installs dependencies, runs migrations, and starts both the Django backend (<code>http://localhost:8000</code>) and the Vue dev server (<code>http://localhost:5173</code>).<br />
<br />
=== Production ===<br />
<br />
* Set <code>DJANGO_ENV=production</code><br />
* Build the frontend: <code>cd frontend && npm run build</code><br />
* Serve with Gunicorn behind a reverse proxy<br />
* Static files are collected into the <code>static/</code> directory<br />
* The production frontend points to <code>https://tyov.yusupov.cloud</code><br />
<br />
== Example: A Finished Character ==<br />
<br />
The following is an example of a character from an actual playthrough stored in the application database. It demonstrates how the game's mechanics play out over an extended narrative.<br />
<br />
=== Karmiš (formerly Ekurzu / Naram) ===<br />
<br />
'''Description:''' Naram was a temple scribe in the ancient city of Mari: meticulous, observant, and deeply entangled in the political and spiritual life of the city. His life was shaped by clay tablets, omens, and whispered secrets carried through palace corridors and temple courtyards. Behind his calm demeanor lies a mind constantly at work—recording, interpreting, and surviving.<br />
<br />
'''Prompts visited:''' 34 prompts across variations, including: 1a, 4a, 11a–c, 12a, 17a, 20a, 24a, 25a, 32a–b, 34a–36a, 37a–41c, 43a–c, 47a, 52a, 57a, 64a, 66a, 68a, 71a, 73a.<br />
<br />
'''Final prompt:''' 73a<br />
<br />
'''Memory slots lost:''' 1 · '''Memory slots gained:''' 1 (net effect: standard 5-memory limit)<br />
<br />
==== Epilogue ====<br />
<br />
<blockquote><br />
He has not died. Let me say that plainly. There will be no grave. He is alive, but quietly, deliberately, and utterly outside your reach.<br />
<br />
When I first met him, I did not understand what he was. He wore his years like dust on old vellum—thin, barely visible, but ever present. [...] Over time, I became his mirror, then his partner, and finally his historian.<br />
<br />
But someone has to begin the telling. Someone has to place the first stone. So this book begins in a house of quiet gardens and low ceilings, where he writes in the mornings and feeds only when he must. [...]<br />
<br />
Just a man who remembered too much, for too long. And chose, in the end, peace.<br />
<br />
— ''Mirelde''<br />
</blockquote><br />
<br />
==== A Life in Summary ====<br />
<br />
Karmiš's story spans roughly three and a half thousand years. It begins in Bronze Age Mesopotamia, where the mortal scribe Naram serves in the temple of Ishtar at Mari—writing omens, navigating palace intrigue, and falling in love with a woman named Hessa who moves through the court "like smoke." His mentor, the High Priest Ibbi-Zamri, is the first person he kills after being turned by the ancient vampire Ashurban the Veiled.<br />
<br />
The early centuries are defined by guilt and exile. Fleeing with his mortal companion Ennatum, the newly-made vampire—now calling himself Ekurzu—struggles to control his hunger. He builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually the hunger wins: he devours Ennatum during a sandstorm and spends the following decades alone.<br />
<br />
The middle game carries the character through the great civilisations of antiquity—Amarna under Akhenaten, the Achaemenid Royal Road, the libraries of Alexandria—always in the role of scribe, forger, or quiet observer. He accumulates skills like ''Silent Cartography'' ("I trace the unseen paths between people, places, and power") and ''Ash-Tongue'' ("I speak in soot and suggestion, in the cracks between laws"), but loses others as the centuries erode his identity: the ability to ''Decipher Ancient Texts'' and even ''I Control the Beast'' both slip away.<br />
<br />
A pivotal relationship develops with the scholar Thoöni, who recognises the name ''Ekurzu'' not as myth but as continuity. Later—after Thoöni's mortal death—her spectral echo begins appearing in the margins of his diary, scratching fragments in languages he can no longer read.<br />
<br />
By the late Roman period Karmiš has lost so many memories that he can barely hold a conversation. The game's memory mechanics enforce this viscerally: eight of his sixteen memories were permanently forgotten, including ''The Turning'' itself—the vampire no longer remembers how he was made. He compensates by keeping diaries, but even those are lost: ''The Walls of Forgetting'' (memory carvings in five scripts beneath a shrine near Carchemish) and ''The Monastery Diary'' both vanish, taking their stored memories with them.<br />
<br />
The final act takes place in early modern Europe. Karmiš witnesses the Atlantic slave trade first-hand and begins compiling ''The Margins of Manifest''—a cipher-folio of names taken from shipping manifests and punishment ledgers. His response to prompt 66a captures the shift:<br />
<br />
<blockquote><br />
''It is no longer a question of restraint. That was a younger version of me—one who believed self-control made me different from the others. Now I am different in purpose, not method. I feed from slavers and call it justice, but the blood tastes the same.''<br />
</blockquote><br />
<br />
His companion in the final centuries is Mirelde of Bracha—an immortal who becomes his mirror, partner, and ultimately his historian. Together they rediscover a clay tablet bearing his original name in a Venetian bookseller's back room (prompt 68a, 1704 CE), and in a ruined estate outside Smyrna Mirelde finds the remains of a life Karmiš can no longer remember.<br />
<br />
At the story's end Karmiš retains only five active memories, three diary memories, two marks (''The Unblinking Eye''—a scar that burns in the presence of lies—and ''The Gesture Forbidden''—an involuntary court gesture mistaken for mockery), and three possessions: his diary ''Kept Against Forgetting'', the clay tablet bearing his name, and the slave-trade folio. Of the eleven characters he encountered, only four remain: Ashurban (his distant maker), Mirelde (his companion), Thoöni's ghost, and a nameless figure known only as ''The One Who Does Not Answer''. Over 34 prompts he accumulated 37 experiences, gained and lost a memory slot each, and burned through three separate diaries.<br />
<br />
The character's story is narrated in the epilogue not by Karmiš himself but by Mirelde, who insists: "He has not died. [...] Just a man who remembered too much, for too long. And chose, in the end, ''peace''."<br />
<br />
== Testing ==<br />
<br />
=== Backend ===<br />
<br />
Tests are run with '''pytest''' and '''pytest-django''':<br />
<br />
<pre><br />
pytest<br />
</pre><br />
<br />
Test files include:<br />
* <code>vampire/test_models.py</code> – model unit tests<br />
* <code>tyov_api/test_api.py</code> – API endpoint integration tests<br />
* <code>tyov_api/test_models.py</code> – API model tests<br />
* <code>authentication/test_views.py</code> – authentication tests<br />
<br />
=== Frontend ===<br />
<br />
End-to-end tests use '''Playwright''':<br />
<br />
<pre><br />
cd frontend<br />
npx playwright test<br />
</pre><br />
<br />
Test specs include:<br />
* <code>e2e/character-creation-workflow.spec.ts</code> – character creation wizard<br />
* <code>e2e/tyov-game.spec.ts</code> – game loop testing<br />
* <code>e2e/vue.spec.ts</code> – general Vue component tests<br />
<br />
== See Also ==<br />
<br />
* ''Thousand Year Old Vampire'' by Tim Hutchings – the original tabletop game<br />
* [[Django (web framework)]]<br />
* [[Vue.js]]<br />
* [[Single-page application]]<br />
<br />
== References ==<br />
<br />
{{Reflist}}<br />
<br />
[[Category:Web applications]]<br />
[[Category:Role-playing video games]]<br />
[[Category:Django (web framework) applications]]<br />
[[Category:Vue.js applications]]<br />
[[Category:Solo role-playing games]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Thousand_Year_Old_Vampire&diff=387Thousand Year Old Vampire2026-04-12T11:21:35Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox <br />
| 01_name = Thousand Year Old Vampire – Web Helper<br />
| 02_logo =<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_programming language = Python (Django 5), TypeScript (Vue 3)<br />
| 05_operating system = Cross-platform (Web)<br />
| 06_genre = Solo RPG Digital Companion<br />
| 07_license = custom<br />
| 08_website = <code>https://tyov.yusupov.cloud</code><br />
}}<br />
<br />
'''Thousand Year Old Vampire – Web Helper''' ('''TYOV-Web''') is a modern web-based implementation of the solo tabletop role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. The application digitises the game's complex mechanics of memory, experience, and character development, allowing players to create and guide a vampire character across centuries of unlife through an interactive browser interface. The backend is built with '''Django 5''' and '''Django REST Framework'''; the frontend is a '''Vue 3''' single-page application.<br />
<br />
== Overview ==<br />
<br />
''Thousand Year Old Vampire'' is a solo storytelling RPG in which a player creates a vampire character and guides it through an increasingly fragmented existence spanning hundreds or thousands of years. The central tension lies in the vampire's deteriorating memory: as an immortal being it accumulates experiences, but its ancient mind can only retain a limited number of memories at any time. Players must constantly choose what to remember and what to forget.<br />
<br />
TYOV-Web fully implements the game's rules—character creation, dice-driven prompt navigation, memory management, diary storage, skills, resources, marks, known characters, and game-ending conditions—in a reactive web interface with persistent server-side storage and a complete audit trail.<br />
<br />
== Game Rules ==<br />
<br />
=== Core Concept ===<br />
<br />
The player creates a vampire and progresses through numbered '''prompts''' (story scenarios). Each prompt asks the player to narrate what happens to the vampire during a particular era. The game is non-linear: dice rolls determine which prompt to visit next, and most prompts have multiple '''variations''' (A, B, C) to prevent repetition.<br />
<br />
=== Character Creation ===<br />
<br />
Character creation follows a guided six-step wizard:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Step !! Description<br />
|-<br />
| 1. Mortal Life || Establish the vampire's name, background, and mortal existence<br />
|-<br />
| 2. Mortal Characters || Define 2–4 NPCs from the vampire's human life (friends, mentors, rivals, lovers)<br />
|-<br />
| 3. Skills || Choose 2–3 starting skills representing mortal expertise<br />
|-<br />
| 4. Resources || Select initial possessions and locations<br />
|-<br />
| 5. Combination Experience || Write a pivotal mortal-life experience that ties characters, skills, and resources together<br />
|-<br />
| 6. The Turning || Narrate how and why the character was turned into a vampire<br />
|}<br />
<br />
=== Memory System ===<br />
<br />
The memory system is the heart of the game:<br />
<br />
* A character may hold a maximum of '''5 active memories''' (adjustable by prompt rules and permanent effects).<br />
* Each memory can contain up to '''3 experiences''' (individual narrative entries).<br />
* When the limit is exceeded, the player must '''forget''' (permanently lose) a memory, or '''move''' one to a '''diary''' (if the character possesses one).<br />
* A '''diary''' is a special resource that stores up to '''4 additional memories''' outside the active limit.<br />
* If the diary resource is lost, all memories stored in it are also lost.<br />
* Some prompts grant or remove permanent memory slots (<code>memory_slot_gain</code>, <code>memory_slot_loss</code>).<br />
<br />
=== Dice Rolling and Prompt Navigation ===<br />
<br />
Each turn the player rolls two dice:<br />
<br />
* '''D10''' (1–10) minus '''D6''' (1–6) = result (range: −5 to +9).<br />
* A '''positive''' result moves forward that many prompts.<br />
* A '''negative''' result moves backward.<br />
* A result of '''zero''' stays at the current prompt number but selects the next unused variation.<br />
<br />
Variations are visited in order A → B → C. If all variations of a prompt have been used, the system finds the next available variation in prompt order.<br />
<br />
=== Turn Structure ===<br />
<br />
Each game turn follows this sequence:<br />
<br />
# '''Prompt Presentation''' – The current prompt text and any special rules are displayed.<br />
# '''Dice Roll''' – The player rolls D10 − D6 to determine the next prompt.<br />
# '''Experience Creation''' – The player writes at least one narrative experience for the current prompt.<br />
# '''Character Updates''' – Skills, resources, marks, and known characters may be added, edited, checked, or removed.<br />
# '''Memory Management''' – The player resolves any memory overflow (forget or move to diary).<br />
# '''Validation''' – The system verifies all rules are satisfied (at least one experience added, memory limits respected, etc.).<br />
# '''Continue''' – All pending changes are atomically committed and the game advances to the next prompt.<br />
<br />
=== Character Attributes ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Attribute !! Description<br />
|-<br />
| '''Skills''' || Learned abilities; can be ''normal'' (latent), ''checked'' (used/active), or ''lost'' (permanently removed).<br />
|-<br />
| '''Resources''' || Possessions or locations; typed as ''portable'' or ''stationary''. One resource may be flagged as a ''diary''.<br />
|-<br />
| '''Marks''' || Physical or psychological scars that accumulate over time.<br />
|-<br />
| '''Known Characters''' || NPCs the vampire has encountered; typed as ''mortal'' or ''immortal''; may be lost (dead, vanished, etc.).<br />
|}<br />
<br />
=== Special Prompt Rules ===<br />
<br />
Certain prompts carry special mechanics encoded as rules:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Rule !! Effect<br />
|-<br />
| <code>no_experience</code> || Experience creation is disabled for this turn<br />
|-<br />
| <code>allow_name_change</code> || The player may change the vampire's name<br />
|-<br />
| <code>memory_modification</code> || The player may edit the text of existing experiences<br />
|-<br />
| <code>memory_slot_loss</code> || Permanent reduction of memory capacity by 1<br />
|-<br />
| <code>memory_slot_gain</code> || Permanent increase of memory capacity by 1<br />
|-<br />
| <code>game_over</code> || The game ends; the player writes an epilogue<br />
|}<br />
<br />
=== Game Ending ===<br />
<br />
The game ends when the player reaches a prompt with the <code>game_over</code> rule (or under other conditions defined by the original game). The player writes an '''epilogue'''—a final reflection on the vampire's story—and the character is archived. A statistics summary shows prompt count, memories, experiences, skills, resources, marks, and characters accumulated during the playthrough.<br />
<br />
== Architecture ==<br />
<br />
=== Technology Stack ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Layer !! Technology !! Version<br />
|-<br />
| Backend framework || Django || 5.0.6<br />
|-<br />
| REST API || Django REST Framework || 3.15.1<br />
|-<br />
| Authentication || Simple JWT (custom) || 5.3.0<br />
|-<br />
| CORS || django-cors-headers || 4.3.1<br />
|-<br />
| Image handling || Pillow || 11.3.0<br />
|-<br />
| Production server || Gunicorn || 21.2.0<br />
|-<br />
| Frontend framework || Vue.js || 3.5<br />
|-<br />
| State management || Pinia || 3.0<br />
|-<br />
| Routing || Vue Router || 4.5<br />
|-<br />
| HTTP client || Axios || 1.10<br />
|-<br />
| CSS framework || Bootstrap || 5.3<br />
|-<br />
| Build tool || Vite || 7.0<br />
|-<br />
| Language || TypeScript || 5.8<br />
|-<br />
| Testing (backend) || pytest + pytest-django || 8.0 / 4.8<br />
|-<br />
| Testing (frontend) || Playwright || 1.53<br />
|}<br />
<br />
=== High-Level Diagram ===<br />
<br />
<pre><br />
┌─────────────────────────────────────────────────┐<br />
│ Vue 3 SPA (TypeScript) │<br />
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│<br />
│ │ Views │ │Components│ │ Pinia Stores ││<br />
│ │ (7 pages)│ │ (14+) │ │ auth/game/theme/ ││<br />
│ │ │ │ │ │ characterCreation ││<br />
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘│<br />
│ └─────────────┴────────────────┘ │<br />
│ │ Axios │<br />
│ ▼ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django REST API │<br />
│ /api/auth/login /api/auth/verify │<br />
│ /api/characters/ (CRUD + game_state, │<br />
│ roll_dice, continue_story, audit_trail) │<br />
│ /api/characters/<id>/memories/ │<br />
│ /api/characters/<id>/experiences/ │<br />
│ /api/characters/<id>/skills/ │<br />
│ /api/characters/<id>/resources/ │<br />
│ /api/characters/<id>/marks/ │<br />
│ /api/characters/<id>/characters/ │<br />
│ /api/characters/<id>/pending-changes/ │<br />
│ /api/prompts/ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django ORM / SQLite │<br />
│ Character · Memory · Experience · Skill │<br />
│ Resource · Mark · GameCharacter · Prompt │<br />
│ PendingChange · GameStateSnapshot │<br />
└─────────────────────────────────────────────────┘<br />
</pre><br />
<br />
== Backend ==<br />
<br />
=== Django Apps ===<br />
<br />
The project is organised into three Django apps plus a settings module:<br />
<br />
{| class="wikitable"<br />
|-<br />
! App !! Purpose<br />
|-<br />
| <code>vampire</code> || Core domain models: Character, Memory, Experience, Skill, Resource, Mark, GameCharacter, Prompt, PendingChange, GameStateSnapshot<br />
|-<br />
| <code>tyov_api</code> || REST API layer: serialisers, viewsets, URL routing, permissions, middleware<br />
|-<br />
| <code>authentication</code> || JWT-based login and token verification endpoints<br />
|-<br />
| <code>tyov_backend</code> || Django project settings, URL root, WSGI/ASGI configuration<br />
|}<br />
<br />
=== Data Models ===<br />
<br />
==== Character ====<br />
<br />
The central model, owned by a Django <code>User</code> via a ForeignKey:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Field !! Type !! Description<br />
|-<br />
| <code>name</code> || CharField(200) || Current name of the vampire<br />
|-<br />
| <code>description</code> || TextField || Background/appearance description<br />
|-<br />
| <code>image</code> || ImageField || Optional character portrait<br />
|-<br />
| <code>current_prompt</code> || CharField(10) || ID of the current prompt (e.g. "17a")<br />
|-<br />
| <code>last_dice_roll</code> || JSONField || Stores D10, D6, and result of the last roll<br />
|-<br />
| <code>visited_prompts</code> || JSONField(list) || List of all prompt IDs visited in order<br />
|-<br />
| <code>memory_slots_lost</code> || IntegerField || Permanent memory slot reductions<br />
|-<br />
| <code>memory_slots_gained</code> || IntegerField || Permanent memory slot increases<br />
|-<br />
| <code>creation_step</code> || IntegerField(1–6) || Tracks progress through the creation wizard<br />
|-<br />
| <code>is_creation_complete</code> || BooleanField || True when all six creation steps are finished<br />
|-<br />
| <code>creation_data</code> || JSONField || Temporary storage during creation<br />
|-<br />
| <code>epilogue</code> || TextField || Player's final reflection (set at game end)<br />
|-<br />
| <code>is_completed</code> || BooleanField || Whether the story has ended<br />
|-<br />
| <code>completed_at</code> || DateTimeField || Timestamp of story completion<br />
|}<br />
<br />
==== Memory ====<br />
<br />
A memory belongs to a Character and holds up to 3 Experiences:<br />
<br />
* <code>title</code> – descriptive name (unique per character)<br />
* <code>in_diary</code> – whether the memory is stored in the diary<br />
* <code>is_lost</code> – whether the memory has been forgotten<br />
<br />
==== Experience ====<br />
<br />
An individual narrative entry within a Memory:<br />
<br />
* <code>title</code> – optional short description<br />
* <code>content</code> – the narrative text<br />
* <code>prompt_id</code> – which prompt generated this experience<br />
* <code>date_info</code> – temporal context (e.g. "Winter, 431 CE")<br />
<br />
==== Skill ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>status</code> – one of <code>normal</code>, <code>checked</code>, or <code>lost</code><br />
<br />
==== Resource ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>resource_type</code> – <code>portable</code> or <code>stationary</code><br />
* <code>is_diary</code> – flags the special diary resource (constrained to one active diary per character)<br />
* <code>is_lost</code><br />
<br />
==== Mark ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>is_lost</code><br />
<br />
==== GameCharacter ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>character_type</code> – <code>mortal</code> or <code>immortal</code><br />
* <code>relationship</code> – e.g. friend, rival, mentor, love, enemy, neutral<br />
* <code>is_lost</code><br />
<br />
==== Prompt ====<br />
<br />
* <code>prompt_id</code> – e.g. "17a", "32b"<br />
* <code>number</code>, <code>variation</code> – parsed components for sorting<br />
* <code>content</code> – the scenario text<br />
* <code>rules</code> – special mechanics as comma-separated tokens (e.g. <code>no_experience, allow_name_change</code>)<br />
<br />
==== PendingChange ====<br />
<br />
Temporary storage for changes before they are atomically committed on "Continue":<br />
<br />
* <code>change_type</code> – experience, memory, skill, resource, mark, or character<br />
* <code>change_data</code> – JSON payload of the change<br />
<br />
==== GameStateSnapshot (Audit Trail) ====<br />
<br />
Automatically created each turn to record the complete game state:<br />
<br />
* <code>turn_number</code> – sequential, starting from 1<br />
* <code>prompt_id</code> / <code>next_prompt_id</code> – transition<br />
* <code>dice_roll</code> – raw dice data<br />
* <code>game_state</code> – full JSON snapshot of all memories, skills, resources, etc.<br />
* <code>changes_applied</code> – JSON array of pending changes that were committed<br />
* <code>created_at</code> – timestamp<br />
<br />
=== API Endpoints ===<br />
<br />
All endpoints require JWT authentication (except login).<br />
<br />
==== Authentication ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| POST || <code>/api/auth/login/</code> || Authenticate with username/password; returns JWT token<br />
|-<br />
| POST || <code>/api/auth/verify/</code> || Verify current token and return user info<br />
|}<br />
<br />
Login is rate-limited to 5 requests per minute per IP.<br />
<br />
==== Characters ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/characters/</code> || List all characters for the authenticated user<br />
|-<br />
| POST || <code>/api/characters/</code> || Create a new character<br />
|-<br />
| GET || <code>/api/characters/{id}/</code> || Retrieve full character detail (prefetched relations)<br />
|-<br />
| PUT/PATCH || <code>/api/characters/{id}/</code> || Update character fields<br />
|-<br />
| DELETE || <code>/api/characters/{id}/</code> || Delete a character<br />
|-<br />
| GET || <code>/api/characters/{id}/game_state/</code> || Complete game state including prompt, validation, dice info<br />
|-<br />
| POST || <code>/api/characters/{id}/roll_dice/</code> || Roll D10 − D6 and store the result<br />
|-<br />
| POST || <code>/api/characters/{id}/continue_story/</code> || Validate, commit pending changes, advance to next prompt<br />
|-<br />
| GET || <code>/api/characters/{id}/audit_trail/</code> || View turn-by-turn audit history<br />
|-<br />
| GET || <code>/api/characters/{id}/game-state-changes/</code> || Timeline of state changes between turns<br />
|}<br />
<br />
==== Nested Character Resources ====<br />
<br />
For each character, full CRUD is available on:<br />
<br />
* <code>/api/characters/{id}/memories/</code> (plus <code>move_to_diary</code> and <code>restore_lost_memory</code> actions)<br />
* <code>/api/characters/{id}/experiences/</code><br />
* <code>/api/characters/{id}/skills/</code><br />
* <code>/api/characters/{id}/resources/</code><br />
* <code>/api/characters/{id}/marks/</code><br />
* <code>/api/characters/{id}/characters/</code> (known NPCs)<br />
* <code>/api/characters/{id}/pending-changes/</code><br />
<br />
==== Prompts ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/prompts/</code> || List all game prompts<br />
|-<br />
| GET || <code>/api/prompts/{prompt_id}/</code> || Retrieve a single prompt by ID<br />
|}<br />
<br />
=== Permissions and Security ===<br />
<br />
* All character data is scoped to the authenticated user via <code>IsCharacterOwner</code> permission.<br />
* JWT tokens are sent as <code>Authorization: Bearer {token}</code> headers.<br />
* The login endpoint is throttled (5/minute) to prevent brute-force attacks.<br />
* All pending changes are processed inside a database '''transaction''' to guarantee atomicity.<br />
* CORS headers are configured via <code>django-cors-headers</code>.<br />
<br />
== Frontend ==<br />
<br />
=== Views (Pages) ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! View !! Route !! Description<br />
|-<br />
| '''LoginView''' || <code>/login</code> || Authentication form; redirects authenticated users to home<br />
|-<br />
| '''HomeView''' || <code>/</code> || Dashboard showing all active characters in a card grid<br />
|-<br />
| '''CharacterCreationView''' || <code>/character-creation/:id</code> || Six-step creation wizard<br />
|-<br />
| '''GameView''' || <code>/game/:characterId</code> || Main game loop: prompt display, experience form, dice rolling, entity management, memory display<br />
|-<br />
| '''GameEndedView''' || <code>/game/:characterId/ended</code> || End-of-story screen with statistics and epilogue<br />
|-<br />
| '''RecordsView''' || <code>/records</code> || Archive of current and completed characters<br />
|-<br />
| '''StoryView''' || <code>/story/:characterId</code> || Narrative timeline with experience history, character stats sidebar, and epilogue<br />
|}<br />
<br />
All routes except <code>/login</code> require authentication. The router guard redirects unauthenticated users.<br />
<br />
=== Key Components ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Component !! Purpose<br />
|-<br />
| '''PromptSection''' || Displays the current prompt text, special rules, and dice roll results<br />
|-<br />
| '''ExperienceForm''' || Form for writing new experiences with title, date, content, and memory selection<br />
|-<br />
| '''MemoriesDisplay''' || Shows active, diary, and lost memories with experience counts; includes move-to-diary, delete, and restore actions<br />
|-<br />
| '''GameDataSection''' || Reusable list for skills, resources, or marks with add/edit/delete controls<br />
|-<br />
| '''CharactersSection''' || Grid of known NPCs with type badges and edit/delete<br />
|-<br />
| '''EntityCreationWindow''' || Draggable modal for creating/editing skills, resources, marks<br />
|-<br />
| '''CharacterCreationWindow''' || Draggable modal for creating/editing NPC characters<br />
|-<br />
| '''ExperienceEditWindow''' || Window for editing existing experience text<br />
|-<br />
| '''DiaryCreationModal''' || Modal for creating a diary resource and moving a memory into it<br />
|-<br />
| '''ConfirmationDialog''' || Generic confirmation dialog for destructive actions<br />
|-<br />
| '''ValidationWarning''' || Displays validation errors when game rules are not satisfied<br />
|}<br />
<br />
=== State Management (Pinia) ===<br />
<br />
Four Pinia stores manage application state:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Store !! Responsibility<br />
|-<br />
| '''auth''' || JWT token, user object, login/logout, token expiry handling<br />
|-<br />
| '''game''' || Characters list, current character, game state, all CRUD actions for entities, dice rolling, story continuation<br />
|-<br />
| '''characterCreation''' || Multi-step wizard data, initial character creation<br />
|-<br />
| '''theme''' || Dark/light mode toggle with localStorage persistence<br />
|}<br />
<br />
=== API Service Layer ===<br />
<br />
* '''<code>api.ts</code>''' – Axios instance with base URL auto-detection (development vs. production), request interceptor for JWT headers, response interceptor for 401/token-expiry handling.<br />
* '''<code>gameService.ts</code>''' – All API call methods: authentication, character CRUD, dice rolling, story continuation, memory/experience/skill/resource/mark/character management.<br />
* '''<code>entityService.ts</code>''' – Generic <code>EntityService</code> class instantiated for skills, resources, marks, and characters for DRY CRUD operations.<br />
<br />
=== Composables ===<br />
<br />
Vue composables encapsulate reusable business logic:<br />
<br />
* '''<code>useGameData()</code>''' – Computed properties derived from the game store (current character, memories, skills, resources, etc.)<br />
* '''<code>useExperienceForm()</code>''' – Form state, validation, memory selection, and reset logic<br />
* '''<code>useEntityManagement()</code>''' – Generic CRUD operations with optional confirmation dialogs<br />
* '''<code>useSkillManagement()</code>''', '''<code>useResourceManagement()</code>''', '''<code>useMarkManagement()</code>''', '''<code>useMemoryManagement()</code>''' – Specialised wrappers<br />
* '''<code>useConfirmationDialog()</code>''' – Promise-based modal confirmation<br />
* '''<code>useMemoryDisplay()</code>''' – Display logic for memories including pending-change awareness<br />
* '''<code>useExperienceDisplay()</code>''' – Markdown rendering for experience content<br />
* '''<code>usePendingChangesDisplay()</code>''' – Badge rendering for undo-able pending changes<br />
<br />
== Audit Trail ==<br />
<br />
The application includes an automatic audit trail that captures the complete game state every time the player advances to a new prompt.<br />
<br />
Each '''GameStateSnapshot''' records:<br />
<br />
* The turn number (sequential from 1)<br />
* The prompt transition (e.g. 36a → 34a)<br />
* The dice roll<br />
* A complete JSON snapshot of all memories, skills, resources, marks, and known characters<br />
* All pending changes that were committed<br />
<br />
The audit trail is accessible via:<br />
<br />
* '''API''': <code>GET /api/characters/{id}/audit_trail/</code> with optional <code>?turn=N</code> and <code>?limit=N</code> parameters<br />
* '''Management command''': <code>python manage.py view_audit_trail {id} [--summary] [--turn N] [--export file.json]</code><br />
* '''Timeline API''': <code>GET /api/characters/{id}/game-state-changes/</code> for a structured timeline of all state changes<br />
<br />
== Deployment ==<br />
<br />
=== Local Development ===<br />
<br />
<pre><br />
.\startup.ps1<br />
</pre><br />
<br />
This script creates a virtual environment, installs dependencies, runs migrations, and starts both the Django backend (<code>http://localhost:8000</code>) and the Vue dev server (<code>http://localhost:5173</code>).<br />
<br />
=== Production ===<br />
<br />
* Set <code>DJANGO_ENV=production</code><br />
* Build the frontend: <code>cd frontend && npm run build</code><br />
* Serve with Gunicorn behind a reverse proxy<br />
* Static files are collected into the <code>static/</code> directory<br />
* The production frontend points to <code>https://tyov.yusupov.cloud</code><br />
<br />
== Example: A Finished Character ==<br />
<br />
The following is an example of a character from an actual playthrough stored in the application database. It demonstrates how the game's mechanics play out over an extended narrative.<br />
<br />
=== Karmiš (formerly Ekurzu / Naram) ===<br />
<br />
'''Description:''' Naram was a temple scribe in the ancient city of Mari: meticulous, observant, and deeply entangled in the political and spiritual life of the city. His life was shaped by clay tablets, omens, and whispered secrets carried through palace corridors and temple courtyards. Behind his calm demeanor lies a mind constantly at work—recording, interpreting, and surviving.<br />
<br />
'''Prompts visited:''' 34 prompts across variations, including: 1a, 4a, 11a–c, 12a, 17a, 20a, 24a, 25a, 32a–b, 34a–36a, 37a–41c, 43a–c, 47a, 52a, 57a, 64a, 66a, 68a, 71a, 73a.<br />
<br />
'''Final prompt:''' 73a<br />
<br />
'''Memory slots lost:''' 1 · '''Memory slots gained:''' 1 (net effect: standard 5-memory limit)<br />
<br />
==== Epilogue ====<br />
<br />
<blockquote><br />
He has not died. Let me say that plainly. There will be no grave, no crumbling tomb, no name worn smooth by time. He is alive—quietly, deliberately, and utterly outside your reach.<br />
<br />
This book is not a memorial. It is a reckoning.<br />
<br />
When I first met him, I did not understand what he was. He wore his years like dust on old vellum—thin, barely visible, but ever present. [...] Over time, I became his mirror, then his partner, and—finally—his historian.<br />
<br />
But someone has to begin the telling. Someone has to place the first stone. So this book begins in a house of quiet gardens and low ceilings, where he writes in the mornings and feeds only when he must. [...]<br />
<br />
Just a man who remembered too much, for too long. And chose, in the end, ''peace''.<br />
<br />
— ''Mirelde''<br />
</blockquote><br />
<br />
==== A Life in Summary ====<br />
<br />
Karmiš's story spans roughly three and a half thousand years. It begins in Bronze Age Mesopotamia, where the mortal scribe Naram serves in the temple of Ishtar at Mari—writing omens, navigating palace intrigue, and falling in love with a woman named Hessa who moves through the court "like smoke." His mentor, the High Priest Ibbi-Zamri, is the first person he kills after being turned by the ancient vampire Ashurban the Veiled.<br />
<br />
The early centuries are defined by guilt and exile. Fleeing with his mortal companion Ennatum, the newly-made vampire—now calling himself Ekurzu—struggles to control his hunger. He builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually the hunger wins: he devours Ennatum during a sandstorm and spends the following decades alone.<br />
<br />
The middle game carries the character through the great civilisations of antiquity—Amarna under Akhenaten, the Achaemenid Royal Road, the libraries of Alexandria—always in the role of scribe, forger, or quiet observer. He accumulates skills like ''Silent Cartography'' ("I trace the unseen paths between people, places, and power") and ''Ash-Tongue'' ("I speak in soot and suggestion, in the cracks between laws"), but loses others as the centuries erode his identity: the ability to ''Decipher Ancient Texts'' and even ''I Control the Beast'' both slip away.<br />
<br />
A pivotal relationship develops with the scholar Thoöni, who recognises the name ''Ekurzu'' not as myth but as continuity. Later—after Thoöni's mortal death—her spectral echo begins appearing in the margins of his diary, scratching fragments in languages he can no longer read.<br />
<br />
By the late Roman period Karmiš has lost so many memories that he can barely hold a conversation. The game's memory mechanics enforce this viscerally: eight of his sixteen memories were permanently forgotten, including ''The Turning'' itself—the vampire no longer remembers how he was made. He compensates by keeping diaries, but even those are lost: ''The Walls of Forgetting'' (memory carvings in five scripts beneath a shrine near Carchemish) and ''The Monastery Diary'' both vanish, taking their stored memories with them.<br />
<br />
The final act takes place in early modern Europe. Karmiš witnesses the Atlantic slave trade first-hand and begins compiling ''The Margins of Manifest''—a cipher-folio of names taken from shipping manifests and punishment ledgers. His response to prompt 66a captures the shift:<br />
<br />
<blockquote><br />
''It is no longer a question of restraint. That was a younger version of me—one who believed self-control made me different from the others. Now I am different in purpose, not method. I feed from slavers and call it justice, but the blood tastes the same.''<br />
</blockquote><br />
<br />
His companion in the final centuries is Mirelde of Bracha—an immortal who becomes his mirror, partner, and ultimately his historian. Together they rediscover a clay tablet bearing his original name in a Venetian bookseller's back room (prompt 68a, 1704 CE), and in a ruined estate outside Smyrna Mirelde finds the remains of a life Karmiš can no longer remember.<br />
<br />
At the story's end Karmiš retains only five active memories, three diary memories, two marks (''The Unblinking Eye''—a scar that burns in the presence of lies—and ''The Gesture Forbidden''—an involuntary court gesture mistaken for mockery), and three possessions: his diary ''Kept Against Forgetting'', the clay tablet bearing his name, and the slave-trade folio. Of the eleven characters he encountered, only four remain: Ashurban (his distant maker), Mirelde (his companion), Thoöni's ghost, and a nameless figure known only as ''The One Who Does Not Answer''. Over 34 prompts he accumulated 37 experiences, gained and lost a memory slot each, and burned through three separate diaries.<br />
<br />
The character's story is narrated in the epilogue not by Karmiš himself but by Mirelde, who insists: "He has not died. [...] Just a man who remembered too much, for too long. And chose, in the end, ''peace''."<br />
<br />
== Testing ==<br />
<br />
=== Backend ===<br />
<br />
Tests are run with '''pytest''' and '''pytest-django''':<br />
<br />
<pre><br />
pytest<br />
</pre><br />
<br />
Test files include:<br />
* <code>vampire/test_models.py</code> – model unit tests<br />
* <code>tyov_api/test_api.py</code> – API endpoint integration tests<br />
* <code>tyov_api/test_models.py</code> – API model tests<br />
* <code>authentication/test_views.py</code> – authentication tests<br />
<br />
=== Frontend ===<br />
<br />
End-to-end tests use '''Playwright''':<br />
<br />
<pre><br />
cd frontend<br />
npx playwright test<br />
</pre><br />
<br />
Test specs include:<br />
* <code>e2e/character-creation-workflow.spec.ts</code> – character creation wizard<br />
* <code>e2e/tyov-game.spec.ts</code> – game loop testing<br />
* <code>e2e/vue.spec.ts</code> – general Vue component tests<br />
<br />
== See Also ==<br />
<br />
* ''Thousand Year Old Vampire'' by Tim Hutchings – the original tabletop game<br />
* [[Django (web framework)]]<br />
* [[Vue.js]]<br />
* [[Single-page application]]<br />
<br />
== References ==<br />
<br />
{{Reflist}}<br />
<br />
[[Category:Web applications]]<br />
[[Category:Role-playing video games]]<br />
[[Category:Django (web framework) applications]]<br />
[[Category:Vue.js applications]]<br />
[[Category:Solo role-playing games]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Thousand_Year_Old_Vampire&diff=386Thousand Year Old Vampire2026-04-12T11:18:24Z<p>Mvuijlst: /* Example Experience: "The Bellies of Ships and Men" (Prompt 64a) */</p>
<hr />
<div>{{Infobox <br />
| 01_name = Thousand Year Old Vampire – Web Helper<br />
| 02_logo =<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_programming language = Python (Django 5), TypeScript (Vue 3)<br />
| 05_operating system = Cross-platform (Web)<br />
| 06_genre = Solo RPG Digital Companion<br />
| 07_license = custom<br />
| 08_website = <code>https://tyov.yusupov.cloud</code><br />
}}<br />
<br />
'''Thousand Year Old Vampire – Web Helper''' ('''TYOV-Web''') is a modern web-based implementation of the solo tabletop role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. The application digitises the game's complex mechanics of memory, experience, and character development, allowing players to create and guide a vampire character across centuries of unlife through an interactive browser interface. The backend is built with '''Django 5''' and '''Django REST Framework'''; the frontend is a '''Vue 3''' single-page application.<br />
<br />
== Overview ==<br />
<br />
''Thousand Year Old Vampire'' is a solo storytelling RPG in which a player creates a vampire character and guides it through an increasingly fragmented existence spanning hundreds or thousands of years. The central tension lies in the vampire's deteriorating memory: as an immortal being it accumulates experiences, but its ancient mind can only retain a limited number of memories at any time. Players must constantly choose what to remember and what to forget.<br />
<br />
TYOV-Web fully implements the game's rules—character creation, dice-driven prompt navigation, memory management, diary storage, skills, resources, marks, known characters, and game-ending conditions—in a reactive web interface with persistent server-side storage and a complete audit trail.<br />
<br />
== Game Rules ==<br />
<br />
=== Core Concept ===<br />
<br />
The player creates a vampire and progresses through numbered '''prompts''' (story scenarios). Each prompt asks the player to narrate what happens to the vampire during a particular era. The game is non-linear: dice rolls determine which prompt to visit next, and most prompts have multiple '''variations''' (A, B, C) to prevent repetition.<br />
<br />
=== Character Creation ===<br />
<br />
Character creation follows a guided six-step wizard:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Step !! Description<br />
|-<br />
| 1. Mortal Life || Establish the vampire's name, background, and mortal existence<br />
|-<br />
| 2. Mortal Characters || Define 2–4 NPCs from the vampire's human life (friends, mentors, rivals, lovers)<br />
|-<br />
| 3. Skills || Choose 2–3 starting skills representing mortal expertise<br />
|-<br />
| 4. Resources || Select initial possessions and locations<br />
|-<br />
| 5. Combination Experience || Write a pivotal mortal-life experience that ties characters, skills, and resources together<br />
|-<br />
| 6. The Turning || Narrate how and why the character was turned into a vampire<br />
|}<br />
<br />
=== Memory System ===<br />
<br />
The memory system is the heart of the game:<br />
<br />
* A character may hold a maximum of '''5 active memories''' (adjustable by prompt rules and permanent effects).<br />
* Each memory can contain up to '''3 experiences''' (individual narrative entries).<br />
* When the limit is exceeded, the player must '''forget''' (permanently lose) a memory, or '''move''' one to a '''diary''' (if the character possesses one).<br />
* A '''diary''' is a special resource that stores up to '''4 additional memories''' outside the active limit.<br />
* If the diary resource is lost, all memories stored in it are also lost.<br />
* Some prompts grant or remove permanent memory slots (<code>memory_slot_gain</code>, <code>memory_slot_loss</code>).<br />
<br />
=== Dice Rolling and Prompt Navigation ===<br />
<br />
Each turn the player rolls two dice:<br />
<br />
* '''D10''' (1–10) minus '''D6''' (1–6) = result (range: −5 to +9).<br />
* A '''positive''' result moves forward that many prompts.<br />
* A '''negative''' result moves backward.<br />
* A result of '''zero''' stays at the current prompt number but selects the next unused variation.<br />
<br />
Variations are visited in order A → B → C. If all variations of a prompt have been used, the system finds the next available variation in prompt order.<br />
<br />
=== Turn Structure ===<br />
<br />
Each game turn follows this sequence:<br />
<br />
# '''Prompt Presentation''' – The current prompt text and any special rules are displayed.<br />
# '''Dice Roll''' – The player rolls D10 − D6 to determine the next prompt.<br />
# '''Experience Creation''' – The player writes at least one narrative experience for the current prompt.<br />
# '''Character Updates''' – Skills, resources, marks, and known characters may be added, edited, checked, or removed.<br />
# '''Memory Management''' – The player resolves any memory overflow (forget or move to diary).<br />
# '''Validation''' – The system verifies all rules are satisfied (at least one experience added, memory limits respected, etc.).<br />
# '''Continue''' – All pending changes are atomically committed and the game advances to the next prompt.<br />
<br />
=== Character Attributes ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Attribute !! Description<br />
|-<br />
| '''Skills''' || Learned abilities; can be ''normal'' (latent), ''checked'' (used/active), or ''lost'' (permanently removed).<br />
|-<br />
| '''Resources''' || Possessions or locations; typed as ''portable'' or ''stationary''. One resource may be flagged as a ''diary''.<br />
|-<br />
| '''Marks''' || Physical or psychological scars that accumulate over time.<br />
|-<br />
| '''Known Characters''' || NPCs the vampire has encountered; typed as ''mortal'' or ''immortal''; may be lost (dead, vanished, etc.).<br />
|}<br />
<br />
=== Special Prompt Rules ===<br />
<br />
Certain prompts carry special mechanics encoded as rules:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Rule !! Effect<br />
|-<br />
| <code>no_experience</code> || Experience creation is disabled for this turn<br />
|-<br />
| <code>allow_name_change</code> || The player may change the vampire's name<br />
|-<br />
| <code>memory_modification</code> || The player may edit the text of existing experiences<br />
|-<br />
| <code>memory_slot_loss</code> || Permanent reduction of memory capacity by 1<br />
|-<br />
| <code>memory_slot_gain</code> || Permanent increase of memory capacity by 1<br />
|-<br />
| <code>game_over</code> || The game ends; the player writes an epilogue<br />
|}<br />
<br />
=== Game Ending ===<br />
<br />
The game ends when the player reaches a prompt with the <code>game_over</code> rule (or under other conditions defined by the original game). The player writes an '''epilogue'''—a final reflection on the vampire's story—and the character is archived. A statistics summary shows prompt count, memories, experiences, skills, resources, marks, and characters accumulated during the playthrough.<br />
<br />
== Architecture ==<br />
<br />
=== Technology Stack ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Layer !! Technology !! Version<br />
|-<br />
| Backend framework || Django || 5.0.6<br />
|-<br />
| REST API || Django REST Framework || 3.15.1<br />
|-<br />
| Authentication || Simple JWT (custom) || 5.3.0<br />
|-<br />
| CORS || django-cors-headers || 4.3.1<br />
|-<br />
| Image handling || Pillow || 11.3.0<br />
|-<br />
| Production server || Gunicorn || 21.2.0<br />
|-<br />
| Frontend framework || Vue.js || 3.5<br />
|-<br />
| State management || Pinia || 3.0<br />
|-<br />
| Routing || Vue Router || 4.5<br />
|-<br />
| HTTP client || Axios || 1.10<br />
|-<br />
| CSS framework || Bootstrap || 5.3<br />
|-<br />
| Build tool || Vite || 7.0<br />
|-<br />
| Language || TypeScript || 5.8<br />
|-<br />
| Testing (backend) || pytest + pytest-django || 8.0 / 4.8<br />
|-<br />
| Testing (frontend) || Playwright || 1.53<br />
|}<br />
<br />
=== High-Level Diagram ===<br />
<br />
<pre><br />
┌─────────────────────────────────────────────────┐<br />
│ Vue 3 SPA (TypeScript) │<br />
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│<br />
│ │ Views │ │Components│ │ Pinia Stores ││<br />
│ │ (7 pages)│ │ (14+) │ │ auth/game/theme/ ││<br />
│ │ │ │ │ │ characterCreation ││<br />
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘│<br />
│ └─────────────┴────────────────┘ │<br />
│ │ Axios │<br />
│ ▼ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django REST API │<br />
│ /api/auth/login /api/auth/verify │<br />
│ /api/characters/ (CRUD + game_state, │<br />
│ roll_dice, continue_story, audit_trail) │<br />
│ /api/characters/<id>/memories/ │<br />
│ /api/characters/<id>/experiences/ │<br />
│ /api/characters/<id>/skills/ │<br />
│ /api/characters/<id>/resources/ │<br />
│ /api/characters/<id>/marks/ │<br />
│ /api/characters/<id>/characters/ │<br />
│ /api/characters/<id>/pending-changes/ │<br />
│ /api/prompts/ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django ORM / SQLite │<br />
│ Character · Memory · Experience · Skill │<br />
│ Resource · Mark · GameCharacter · Prompt │<br />
│ PendingChange · GameStateSnapshot │<br />
└─────────────────────────────────────────────────┘<br />
</pre><br />
<br />
== Backend ==<br />
<br />
=== Django Apps ===<br />
<br />
The project is organised into three Django apps plus a settings module:<br />
<br />
{| class="wikitable"<br />
|-<br />
! App !! Purpose<br />
|-<br />
| <code>vampire</code> || Core domain models: Character, Memory, Experience, Skill, Resource, Mark, GameCharacter, Prompt, PendingChange, GameStateSnapshot<br />
|-<br />
| <code>tyov_api</code> || REST API layer: serialisers, viewsets, URL routing, permissions, middleware<br />
|-<br />
| <code>authentication</code> || JWT-based login and token verification endpoints<br />
|-<br />
| <code>tyov_backend</code> || Django project settings, URL root, WSGI/ASGI configuration<br />
|}<br />
<br />
=== Data Models ===<br />
<br />
==== Character ====<br />
<br />
The central model, owned by a Django <code>User</code> via a ForeignKey:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Field !! Type !! Description<br />
|-<br />
| <code>name</code> || CharField(200) || Current name of the vampire<br />
|-<br />
| <code>description</code> || TextField || Background/appearance description<br />
|-<br />
| <code>image</code> || ImageField || Optional character portrait<br />
|-<br />
| <code>current_prompt</code> || CharField(10) || ID of the current prompt (e.g. "17a")<br />
|-<br />
| <code>last_dice_roll</code> || JSONField || Stores D10, D6, and result of the last roll<br />
|-<br />
| <code>visited_prompts</code> || JSONField(list) || List of all prompt IDs visited in order<br />
|-<br />
| <code>memory_slots_lost</code> || IntegerField || Permanent memory slot reductions<br />
|-<br />
| <code>memory_slots_gained</code> || IntegerField || Permanent memory slot increases<br />
|-<br />
| <code>creation_step</code> || IntegerField(1–6) || Tracks progress through the creation wizard<br />
|-<br />
| <code>is_creation_complete</code> || BooleanField || True when all six creation steps are finished<br />
|-<br />
| <code>creation_data</code> || JSONField || Temporary storage during creation<br />
|-<br />
| <code>epilogue</code> || TextField || Player's final reflection (set at game end)<br />
|-<br />
| <code>is_completed</code> || BooleanField || Whether the story has ended<br />
|-<br />
| <code>completed_at</code> || DateTimeField || Timestamp of story completion<br />
|}<br />
<br />
==== Memory ====<br />
<br />
A memory belongs to a Character and holds up to 3 Experiences:<br />
<br />
* <code>title</code> – descriptive name (unique per character)<br />
* <code>in_diary</code> – whether the memory is stored in the diary<br />
* <code>is_lost</code> – whether the memory has been forgotten<br />
<br />
==== Experience ====<br />
<br />
An individual narrative entry within a Memory:<br />
<br />
* <code>title</code> – optional short description<br />
* <code>content</code> – the narrative text<br />
* <code>prompt_id</code> – which prompt generated this experience<br />
* <code>date_info</code> – temporal context (e.g. "Winter, 431 CE")<br />
<br />
==== Skill ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>status</code> – one of <code>normal</code>, <code>checked</code>, or <code>lost</code><br />
<br />
==== Resource ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>resource_type</code> – <code>portable</code> or <code>stationary</code><br />
* <code>is_diary</code> – flags the special diary resource (constrained to one active diary per character)<br />
* <code>is_lost</code><br />
<br />
==== Mark ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>is_lost</code><br />
<br />
==== GameCharacter ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>character_type</code> – <code>mortal</code> or <code>immortal</code><br />
* <code>relationship</code> – e.g. friend, rival, mentor, love, enemy, neutral<br />
* <code>is_lost</code><br />
<br />
==== Prompt ====<br />
<br />
* <code>prompt_id</code> – e.g. "17a", "32b"<br />
* <code>number</code>, <code>variation</code> – parsed components for sorting<br />
* <code>content</code> – the scenario text<br />
* <code>rules</code> – special mechanics as comma-separated tokens (e.g. <code>no_experience, allow_name_change</code>)<br />
<br />
==== PendingChange ====<br />
<br />
Temporary storage for changes before they are atomically committed on "Continue":<br />
<br />
* <code>change_type</code> – experience, memory, skill, resource, mark, or character<br />
* <code>change_data</code> – JSON payload of the change<br />
<br />
==== GameStateSnapshot (Audit Trail) ====<br />
<br />
Automatically created each turn to record the complete game state:<br />
<br />
* <code>turn_number</code> – sequential, starting from 1<br />
* <code>prompt_id</code> / <code>next_prompt_id</code> – transition<br />
* <code>dice_roll</code> – raw dice data<br />
* <code>game_state</code> – full JSON snapshot of all memories, skills, resources, etc.<br />
* <code>changes_applied</code> – JSON array of pending changes that were committed<br />
* <code>created_at</code> – timestamp<br />
<br />
=== API Endpoints ===<br />
<br />
All endpoints require JWT authentication (except login).<br />
<br />
==== Authentication ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| POST || <code>/api/auth/login/</code> || Authenticate with username/password; returns JWT token<br />
|-<br />
| POST || <code>/api/auth/verify/</code> || Verify current token and return user info<br />
|}<br />
<br />
Login is rate-limited to 5 requests per minute per IP.<br />
<br />
==== Characters ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/characters/</code> || List all characters for the authenticated user<br />
|-<br />
| POST || <code>/api/characters/</code> || Create a new character<br />
|-<br />
| GET || <code>/api/characters/{id}/</code> || Retrieve full character detail (prefetched relations)<br />
|-<br />
| PUT/PATCH || <code>/api/characters/{id}/</code> || Update character fields<br />
|-<br />
| DELETE || <code>/api/characters/{id}/</code> || Delete a character<br />
|-<br />
| GET || <code>/api/characters/{id}/game_state/</code> || Complete game state including prompt, validation, dice info<br />
|-<br />
| POST || <code>/api/characters/{id}/roll_dice/</code> || Roll D10 − D6 and store the result<br />
|-<br />
| POST || <code>/api/characters/{id}/continue_story/</code> || Validate, commit pending changes, advance to next prompt<br />
|-<br />
| GET || <code>/api/characters/{id}/audit_trail/</code> || View turn-by-turn audit history<br />
|-<br />
| GET || <code>/api/characters/{id}/game-state-changes/</code> || Timeline of state changes between turns<br />
|}<br />
<br />
==== Nested Character Resources ====<br />
<br />
For each character, full CRUD is available on:<br />
<br />
* <code>/api/characters/{id}/memories/</code> (plus <code>move_to_diary</code> and <code>restore_lost_memory</code> actions)<br />
* <code>/api/characters/{id}/experiences/</code><br />
* <code>/api/characters/{id}/skills/</code><br />
* <code>/api/characters/{id}/resources/</code><br />
* <code>/api/characters/{id}/marks/</code><br />
* <code>/api/characters/{id}/characters/</code> (known NPCs)<br />
* <code>/api/characters/{id}/pending-changes/</code><br />
<br />
==== Prompts ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/prompts/</code> || List all game prompts<br />
|-<br />
| GET || <code>/api/prompts/{prompt_id}/</code> || Retrieve a single prompt by ID<br />
|}<br />
<br />
=== Permissions and Security ===<br />
<br />
* All character data is scoped to the authenticated user via <code>IsCharacterOwner</code> permission.<br />
* JWT tokens are sent as <code>Authorization: Bearer {token}</code> headers.<br />
* The login endpoint is throttled (5/minute) to prevent brute-force attacks.<br />
* All pending changes are processed inside a database '''transaction''' to guarantee atomicity.<br />
* CORS headers are configured via <code>django-cors-headers</code>.<br />
<br />
== Frontend ==<br />
<br />
=== Views (Pages) ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! View !! Route !! Description<br />
|-<br />
| '''LoginView''' || <code>/login</code> || Authentication form; redirects authenticated users to home<br />
|-<br />
| '''HomeView''' || <code>/</code> || Dashboard showing all active characters in a card grid<br />
|-<br />
| '''CharacterCreationView''' || <code>/character-creation/:id</code> || Six-step creation wizard<br />
|-<br />
| '''GameView''' || <code>/game/:characterId</code> || Main game loop: prompt display, experience form, dice rolling, entity management, memory display<br />
|-<br />
| '''GameEndedView''' || <code>/game/:characterId/ended</code> || End-of-story screen with statistics and epilogue<br />
|-<br />
| '''RecordsView''' || <code>/records</code> || Archive of current and completed characters<br />
|-<br />
| '''StoryView''' || <code>/story/:characterId</code> || Narrative timeline with experience history, character stats sidebar, and epilogue<br />
|}<br />
<br />
All routes except <code>/login</code> require authentication. The router guard redirects unauthenticated users.<br />
<br />
=== Key Components ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Component !! Purpose<br />
|-<br />
| '''PromptSection''' || Displays the current prompt text, special rules, and dice roll results<br />
|-<br />
| '''ExperienceForm''' || Form for writing new experiences with title, date, content, and memory selection<br />
|-<br />
| '''MemoriesDisplay''' || Shows active, diary, and lost memories with experience counts; includes move-to-diary, delete, and restore actions<br />
|-<br />
| '''GameDataSection''' || Reusable list for skills, resources, or marks with add/edit/delete controls<br />
|-<br />
| '''CharactersSection''' || Grid of known NPCs with type badges and edit/delete<br />
|-<br />
| '''EntityCreationWindow''' || Draggable modal for creating/editing skills, resources, marks<br />
|-<br />
| '''CharacterCreationWindow''' || Draggable modal for creating/editing NPC characters<br />
|-<br />
| '''ExperienceEditWindow''' || Window for editing existing experience text<br />
|-<br />
| '''DiaryCreationModal''' || Modal for creating a diary resource and moving a memory into it<br />
|-<br />
| '''ConfirmationDialog''' || Generic confirmation dialog for destructive actions<br />
|-<br />
| '''ValidationWarning''' || Displays validation errors when game rules are not satisfied<br />
|}<br />
<br />
=== State Management (Pinia) ===<br />
<br />
Four Pinia stores manage application state:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Store !! Responsibility<br />
|-<br />
| '''auth''' || JWT token, user object, login/logout, token expiry handling<br />
|-<br />
| '''game''' || Characters list, current character, game state, all CRUD actions for entities, dice rolling, story continuation<br />
|-<br />
| '''characterCreation''' || Multi-step wizard data, initial character creation<br />
|-<br />
| '''theme''' || Dark/light mode toggle with localStorage persistence<br />
|}<br />
<br />
=== API Service Layer ===<br />
<br />
* '''<code>api.ts</code>''' – Axios instance with base URL auto-detection (development vs. production), request interceptor for JWT headers, response interceptor for 401/token-expiry handling.<br />
* '''<code>gameService.ts</code>''' – All API call methods: authentication, character CRUD, dice rolling, story continuation, memory/experience/skill/resource/mark/character management.<br />
* '''<code>entityService.ts</code>''' – Generic <code>EntityService</code> class instantiated for skills, resources, marks, and characters for DRY CRUD operations.<br />
<br />
=== Composables ===<br />
<br />
Vue composables encapsulate reusable business logic:<br />
<br />
* '''<code>useGameData()</code>''' – Computed properties derived from the game store (current character, memories, skills, resources, etc.)<br />
* '''<code>useExperienceForm()</code>''' – Form state, validation, memory selection, and reset logic<br />
* '''<code>useEntityManagement()</code>''' – Generic CRUD operations with optional confirmation dialogs<br />
* '''<code>useSkillManagement()</code>''', '''<code>useResourceManagement()</code>''', '''<code>useMarkManagement()</code>''', '''<code>useMemoryManagement()</code>''' – Specialised wrappers<br />
* '''<code>useConfirmationDialog()</code>''' – Promise-based modal confirmation<br />
* '''<code>useMemoryDisplay()</code>''' – Display logic for memories including pending-change awareness<br />
* '''<code>useExperienceDisplay()</code>''' – Markdown rendering for experience content<br />
* '''<code>usePendingChangesDisplay()</code>''' – Badge rendering for undo-able pending changes<br />
<br />
== Audit Trail ==<br />
<br />
The application includes an automatic audit trail that captures the complete game state every time the player advances to a new prompt.<br />
<br />
Each '''GameStateSnapshot''' records:<br />
<br />
* The turn number (sequential from 1)<br />
* The prompt transition (e.g. 36a → 34a)<br />
* The dice roll<br />
* A complete JSON snapshot of all memories, skills, resources, marks, and known characters<br />
* All pending changes that were committed<br />
<br />
The audit trail is accessible via:<br />
<br />
* '''API''': <code>GET /api/characters/{id}/audit_trail/</code> with optional <code>?turn=N</code> and <code>?limit=N</code> parameters<br />
* '''Management command''': <code>python manage.py view_audit_trail {id} [--summary] [--turn N] [--export file.json]</code><br />
* '''Timeline API''': <code>GET /api/characters/{id}/game-state-changes/</code> for a structured timeline of all state changes<br />
<br />
== Deployment ==<br />
<br />
=== Local Development ===<br />
<br />
<pre><br />
.\startup.ps1<br />
</pre><br />
<br />
This script creates a virtual environment, installs dependencies, runs migrations, and starts both the Django backend (<code>http://localhost:8000</code>) and the Vue dev server (<code>http://localhost:5173</code>).<br />
<br />
=== Production ===<br />
<br />
* Set <code>DJANGO_ENV=production</code><br />
* Build the frontend: <code>cd frontend && npm run build</code><br />
* Serve with Gunicorn behind a reverse proxy<br />
* Static files are collected into the <code>static/</code> directory<br />
* The production frontend points to <code>https://tyov.yusupov.cloud</code><br />
<br />
== Example: A Finished Character ==<br />
<br />
The following is an example of a character from an actual playthrough stored in the application database. It demonstrates how the game's mechanics play out over an extended narrative.<br />
<br />
=== Karmiš (formerly Ekurzu / Naram) ===<br />
<br />
'''Description:''' Naram was a temple scribe in the ancient city of Mari: meticulous, observant, and deeply entangled in the political and spiritual life of the city. His life was shaped by clay tablets, omens, and whispered secrets carried through palace corridors and temple courtyards. Behind his calm demeanor lies a mind constantly at work—recording, interpreting, and surviving.<br />
<br />
'''Prompts visited:''' 34 prompts across variations, including: 1a, 4a, 11a–c, 12a, 17a, 20a, 24a, 25a, 32a–b, 34a–36a, 37a–41c, 43a–c, 47a, 52a, 57a, 64a, 66a, 68a, 71a, 73a.<br />
<br />
'''Final prompt:''' 73a<br />
<br />
'''Memory slots lost:''' 1 · '''Memory slots gained:''' 1 (net effect: standard 5-memory limit)<br />
<br />
==== Epilogue ====<br />
<br />
<blockquote><br />
He has not died. Let me say that plainly. There will be no grave. He is alive, but quietly, deliberately, and utterly outside your reach.<br />
<br />
When I first met him, I did not understand what he was. He wore his years like dust on old vellum—thin, barely visible, but ever present. [...] Over time, I became his mirror, then his partner, and finally his historian.<br />
<br />
But someone has to begin the telling. Someone has to place the first stone. So this book begins in a house of quiet gardens and low ceilings, where he writes in the mornings and feeds only when he must. [...]<br />
<br />
Just a man who remembered too much, for too long. And chose, in the end, ''peace''.<br />
<br />
— ''Mirelde''<br />
</blockquote><br />
<br />
==== Statistics ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Metric !! Count<br />
|-<br />
| Total memories || 16<br />
|-<br />
| Active memories || 5<br />
|-<br />
| Diary memories || 3<br />
|-<br />
| Lost (forgotten) memories || 8<br />
|-<br />
| Total experiences || 37<br />
|-<br />
| Skills || 11 (3 lost during play)<br />
|-<br />
| Resources || 10 (6 lost during play)<br />
|-<br />
| Marks || 2<br />
|-<br />
| Known characters || 11 (6 lost during play)<br />
|}<br />
<br />
==== Active Memories (at end of game) ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Memory Title !! Location !! Experiences<br />
|-<br />
| Memory 1 || Active || "Mortal life" (Initial), "The Name Given in Ash" (24a)<br />
|-<br />
| The Thorn and the Quill || Active || 1 experience (35a)<br />
|-<br />
| The Light That Does Not Burn || Active || "The Dawn at Mirelde's Fire" (52a), "The Dust in the Foundation" (57a)<br />
|-<br />
| We Were Not Counted Among the Cargo || Active || "The Bellies of Ships and Men" (64a), "Ink Without Meaning" (66a)<br />
|-<br />
| Echoes Before the Self Was Named || Active || "The Weight in the Smoke" (71a), "The Clay That Knew My Name" (68a)<br />
|}<br />
<br />
==== Diary Memories ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Memory Title !! Experiences<br />
|-<br />
| The Hill That Waits || "The Hollow Beneath the Cairn" (40a), "The Ring Beneath the Clay" (43c), "The Face Returned Through Time" (44a)<br />
|-<br />
| Ash of the Ledger || "The Last Ledger Vanishes" (38a), "The Fog Beneath Names" (39b), "The Weight of Unspoken Words" (34a)<br />
|-<br />
| The Fever-Ledger || "The Illness in Karkheda" (36a), "The Name That Returns in Ash" (41c), "The Echo That Cannot Translate" (47a)<br />
|}<br />
<br />
==== Lost Memories ====<br />
<br />
Eight memories were forgotten over the course of the game, including "The Forged Omen" (Memory 2), "Hessa's Last Message" (Memory 3), "Duel of Stars and Signs" (Memory 4), "The Turning", "The Name That Cannot Burn", "The Blood Between Accusations", "Trade Beneath Empire", and "What Was Meant to Last". These losses illustrate the game's core mechanic: as new experiences accumulate, the vampire is forced to sacrifice older memories, creating a poignant sense of identity erosion across the centuries.<br />
<br />
==== Skills ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Skill !! Status !! Description (excerpt)<br />
|-<br />
| Ash-Tongue || {{Checked}} || "I speak in soot and suggestion, in the cracks between laws."<br />
|-<br />
| Bloodthirsty || {{Lost}} || "The scent of mortal blood calls to me like a hymn in the dark."<br />
|-<br />
| Ceremonial Composure || {{Checked}} || "In the presence of gods or kings, my face is unreadable."<br />
|-<br />
| Decipher Ancient Texts || {{Lost}} || "I can read languages long dead and spot forgeries."<br />
|-<br />
| I Control the Beast || {{Lost}} || "When the thirst rises, I do not flinch. I meet the monster's gaze."<br />
|-<br />
| Ledger Without End || Normal || "Born from the quiet rituals of inventory and account."<br />
|-<br />
| Physick of the Pale Vein || Normal || "I feed gently, beneath the guise of care."<br />
|-<br />
| Remain in Unknowing || {{Checked}} || "I do not flee the edges of memory."<br />
|-<br />
| Silent Cartography || {{Checked}} || "I trace the unseen paths between people, places, and power."<br />
|-<br />
| Snare and Stillness || {{Checked}} || "I move with silence that makes mortals forget they heard me."<br />
|-<br />
| Tongue of the Unnamed || Normal || "I no longer understand the languages of my past, but I wear the sounds of others like masks."<br />
|}<br />
<br />
==== Resources ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Resource !! Type !! Status !! Notes<br />
|-<br />
| Kept Against Forgetting || Portable / '''Diary''' || Active || The character's diary; written with Mirelde<br />
|-<br />
| Tablet Bearing My Name || Portable || Active || A clay tablet from the ancient past, rediscovered<br />
|-<br />
| The Margins of Manifest || Portable || Active || A cipher-folio cataloguing names of the enslaved<br />
|-<br />
| Burrowed Sanctum || Portable || Lost || An earthen chamber beneath a forgotten altar<br />
|-<br />
| Chamber of Whispers || Stationary || Lost || A hidden storeroom beneath the temple of Ishtar<br />
|-<br />
| Clay Tablets and Reed Stylus || Portable || Lost || Writing implements used by instinct, not understanding<br />
|-<br />
| Hidden Archive Tablet || Portable || Lost || A tablet inscribed with dynasty-breaking truths<br />
|-<br />
| The Monastery Diary || Portable / Diary || Lost || A former diary, lost when the monastery fell<br />
|-<br />
| The Silent Authority || Portable || Lost || A carved seal whose symbols can no longer be read<br />
|-<br />
| The Walls of Forgetting || Stationary / Diary || Lost || Memory carvings in five scripts beneath a forgotten shrine<br />
|}<br />
<br />
==== Known Characters ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Name !! Type !! Relationship !! Status<br />
|-<br />
| Ashurban the Veiled || Immortal || Neutral || Active<br />
|-<br />
| Mirelde of Bracha || Immortal || Friend || Active<br />
|-<br />
| The One Who Does Not Answer || Mortal || Neutral || Active<br />
|-<br />
| Thoöni (spectral) || Immortal || Neutral || Active<br />
|-<br />
| Belatu || Mortal || Rival || Lost<br />
|-<br />
| Ennatum || Mortal || Friend || Lost<br />
|-<br />
| Hessa || Mortal || Love || Lost<br />
|-<br />
| Ibbi-Zamri || Mortal || Mentor || Lost<br />
|-<br />
| Mekha || Mortal || Enemy || Lost<br />
|-<br />
| Pelagon || Mortal || Enemy || Lost<br />
|-<br />
| Thoöni (scholar) || Mortal || Friend || Lost<br />
|}<br />
<br />
==== Marks ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Mark !! Description<br />
|-<br />
| The Unblinking Eye || An ancient eye-like scar below the collarbone; burns faintly in the presence of lies<br />
|-<br />
| The Gesture Forbidden || An involuntary three-fingered gesture of silence, often mistaken for mockery<br />
|}<br />
<br />
==== Example Experience: "The Bellies of Ships and Men" (Prompt 64a) ====<br />
<br />
<blockquote><br />
They arrived in numbers too vast to count: pressed between barrels, chained to holds slick with piss and seawater, branded, sick, broken. And the sailors were not much better.<br />
<br />
The ships would come in [...]<br />
</blockquote><br />
<br />
''Date: around 1510 CE''<br />
<br />
This experience is part of the memory "We Were Not Counted Among the Cargo", illustrating the vampire's witness to the Atlantic slave trade—one of many historical eras the character passes through during a millennium-spanning story.<br />
<br />
== Testing ==<br />
<br />
=== Backend ===<br />
<br />
Tests are run with '''pytest''' and '''pytest-django''':<br />
<br />
<pre><br />
pytest<br />
</pre><br />
<br />
Test files include:<br />
* <code>vampire/test_models.py</code> – model unit tests<br />
* <code>tyov_api/test_api.py</code> – API endpoint integration tests<br />
* <code>tyov_api/test_models.py</code> – API model tests<br />
* <code>authentication/test_views.py</code> – authentication tests<br />
<br />
=== Frontend ===<br />
<br />
End-to-end tests use '''Playwright''':<br />
<br />
<pre><br />
cd frontend<br />
npx playwright test<br />
</pre><br />
<br />
Test specs include:<br />
* <code>e2e/character-creation-workflow.spec.ts</code> – character creation wizard<br />
* <code>e2e/tyov-game.spec.ts</code> – game loop testing<br />
* <code>e2e/vue.spec.ts</code> – general Vue component tests<br />
<br />
== See Also ==<br />
<br />
* ''Thousand Year Old Vampire'' by Tim Hutchings – the original tabletop game<br />
* [[Django (web framework)]]<br />
* [[Vue.js]]<br />
* [[Single-page application]]<br />
<br />
== References ==<br />
<br />
{{Reflist}}<br />
<br />
[[Category:Web applications]]<br />
[[Category:Role-playing video games]]<br />
[[Category:Django (web framework) applications]]<br />
[[Category:Vue.js applications]]<br />
[[Category:Solo role-playing games]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Thousand_Year_Old_Vampire&diff=385Thousand Year Old Vampire2026-04-12T11:17:32Z<p>Mvuijlst: /* Epilogue */</p>
<hr />
<div>{{Infobox <br />
| 01_name = Thousand Year Old Vampire – Web Helper<br />
| 02_logo =<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_programming language = Python (Django 5), TypeScript (Vue 3)<br />
| 05_operating system = Cross-platform (Web)<br />
| 06_genre = Solo RPG Digital Companion<br />
| 07_license = custom<br />
| 08_website = <code>https://tyov.yusupov.cloud</code><br />
}}<br />
<br />
'''Thousand Year Old Vampire – Web Helper''' ('''TYOV-Web''') is a modern web-based implementation of the solo tabletop role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. The application digitises the game's complex mechanics of memory, experience, and character development, allowing players to create and guide a vampire character across centuries of unlife through an interactive browser interface. The backend is built with '''Django 5''' and '''Django REST Framework'''; the frontend is a '''Vue 3''' single-page application.<br />
<br />
== Overview ==<br />
<br />
''Thousand Year Old Vampire'' is a solo storytelling RPG in which a player creates a vampire character and guides it through an increasingly fragmented existence spanning hundreds or thousands of years. The central tension lies in the vampire's deteriorating memory: as an immortal being it accumulates experiences, but its ancient mind can only retain a limited number of memories at any time. Players must constantly choose what to remember and what to forget.<br />
<br />
TYOV-Web fully implements the game's rules—character creation, dice-driven prompt navigation, memory management, diary storage, skills, resources, marks, known characters, and game-ending conditions—in a reactive web interface with persistent server-side storage and a complete audit trail.<br />
<br />
== Game Rules ==<br />
<br />
=== Core Concept ===<br />
<br />
The player creates a vampire and progresses through numbered '''prompts''' (story scenarios). Each prompt asks the player to narrate what happens to the vampire during a particular era. The game is non-linear: dice rolls determine which prompt to visit next, and most prompts have multiple '''variations''' (A, B, C) to prevent repetition.<br />
<br />
=== Character Creation ===<br />
<br />
Character creation follows a guided six-step wizard:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Step !! Description<br />
|-<br />
| 1. Mortal Life || Establish the vampire's name, background, and mortal existence<br />
|-<br />
| 2. Mortal Characters || Define 2–4 NPCs from the vampire's human life (friends, mentors, rivals, lovers)<br />
|-<br />
| 3. Skills || Choose 2–3 starting skills representing mortal expertise<br />
|-<br />
| 4. Resources || Select initial possessions and locations<br />
|-<br />
| 5. Combination Experience || Write a pivotal mortal-life experience that ties characters, skills, and resources together<br />
|-<br />
| 6. The Turning || Narrate how and why the character was turned into a vampire<br />
|}<br />
<br />
=== Memory System ===<br />
<br />
The memory system is the heart of the game:<br />
<br />
* A character may hold a maximum of '''5 active memories''' (adjustable by prompt rules and permanent effects).<br />
* Each memory can contain up to '''3 experiences''' (individual narrative entries).<br />
* When the limit is exceeded, the player must '''forget''' (permanently lose) a memory, or '''move''' one to a '''diary''' (if the character possesses one).<br />
* A '''diary''' is a special resource that stores up to '''4 additional memories''' outside the active limit.<br />
* If the diary resource is lost, all memories stored in it are also lost.<br />
* Some prompts grant or remove permanent memory slots (<code>memory_slot_gain</code>, <code>memory_slot_loss</code>).<br />
<br />
=== Dice Rolling and Prompt Navigation ===<br />
<br />
Each turn the player rolls two dice:<br />
<br />
* '''D10''' (1–10) minus '''D6''' (1–6) = result (range: −5 to +9).<br />
* A '''positive''' result moves forward that many prompts.<br />
* A '''negative''' result moves backward.<br />
* A result of '''zero''' stays at the current prompt number but selects the next unused variation.<br />
<br />
Variations are visited in order A → B → C. If all variations of a prompt have been used, the system finds the next available variation in prompt order.<br />
<br />
=== Turn Structure ===<br />
<br />
Each game turn follows this sequence:<br />
<br />
# '''Prompt Presentation''' – The current prompt text and any special rules are displayed.<br />
# '''Dice Roll''' – The player rolls D10 − D6 to determine the next prompt.<br />
# '''Experience Creation''' – The player writes at least one narrative experience for the current prompt.<br />
# '''Character Updates''' – Skills, resources, marks, and known characters may be added, edited, checked, or removed.<br />
# '''Memory Management''' – The player resolves any memory overflow (forget or move to diary).<br />
# '''Validation''' – The system verifies all rules are satisfied (at least one experience added, memory limits respected, etc.).<br />
# '''Continue''' – All pending changes are atomically committed and the game advances to the next prompt.<br />
<br />
=== Character Attributes ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Attribute !! Description<br />
|-<br />
| '''Skills''' || Learned abilities; can be ''normal'' (latent), ''checked'' (used/active), or ''lost'' (permanently removed).<br />
|-<br />
| '''Resources''' || Possessions or locations; typed as ''portable'' or ''stationary''. One resource may be flagged as a ''diary''.<br />
|-<br />
| '''Marks''' || Physical or psychological scars that accumulate over time.<br />
|-<br />
| '''Known Characters''' || NPCs the vampire has encountered; typed as ''mortal'' or ''immortal''; may be lost (dead, vanished, etc.).<br />
|}<br />
<br />
=== Special Prompt Rules ===<br />
<br />
Certain prompts carry special mechanics encoded as rules:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Rule !! Effect<br />
|-<br />
| <code>no_experience</code> || Experience creation is disabled for this turn<br />
|-<br />
| <code>allow_name_change</code> || The player may change the vampire's name<br />
|-<br />
| <code>memory_modification</code> || The player may edit the text of existing experiences<br />
|-<br />
| <code>memory_slot_loss</code> || Permanent reduction of memory capacity by 1<br />
|-<br />
| <code>memory_slot_gain</code> || Permanent increase of memory capacity by 1<br />
|-<br />
| <code>game_over</code> || The game ends; the player writes an epilogue<br />
|}<br />
<br />
=== Game Ending ===<br />
<br />
The game ends when the player reaches a prompt with the <code>game_over</code> rule (or under other conditions defined by the original game). The player writes an '''epilogue'''—a final reflection on the vampire's story—and the character is archived. A statistics summary shows prompt count, memories, experiences, skills, resources, marks, and characters accumulated during the playthrough.<br />
<br />
== Architecture ==<br />
<br />
=== Technology Stack ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Layer !! Technology !! Version<br />
|-<br />
| Backend framework || Django || 5.0.6<br />
|-<br />
| REST API || Django REST Framework || 3.15.1<br />
|-<br />
| Authentication || Simple JWT (custom) || 5.3.0<br />
|-<br />
| CORS || django-cors-headers || 4.3.1<br />
|-<br />
| Image handling || Pillow || 11.3.0<br />
|-<br />
| Production server || Gunicorn || 21.2.0<br />
|-<br />
| Frontend framework || Vue.js || 3.5<br />
|-<br />
| State management || Pinia || 3.0<br />
|-<br />
| Routing || Vue Router || 4.5<br />
|-<br />
| HTTP client || Axios || 1.10<br />
|-<br />
| CSS framework || Bootstrap || 5.3<br />
|-<br />
| Build tool || Vite || 7.0<br />
|-<br />
| Language || TypeScript || 5.8<br />
|-<br />
| Testing (backend) || pytest + pytest-django || 8.0 / 4.8<br />
|-<br />
| Testing (frontend) || Playwright || 1.53<br />
|}<br />
<br />
=== High-Level Diagram ===<br />
<br />
<pre><br />
┌─────────────────────────────────────────────────┐<br />
│ Vue 3 SPA (TypeScript) │<br />
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│<br />
│ │ Views │ │Components│ │ Pinia Stores ││<br />
│ │ (7 pages)│ │ (14+) │ │ auth/game/theme/ ││<br />
│ │ │ │ │ │ characterCreation ││<br />
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘│<br />
│ └─────────────┴────────────────┘ │<br />
│ │ Axios │<br />
│ ▼ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django REST API │<br />
│ /api/auth/login /api/auth/verify │<br />
│ /api/characters/ (CRUD + game_state, │<br />
│ roll_dice, continue_story, audit_trail) │<br />
│ /api/characters/<id>/memories/ │<br />
│ /api/characters/<id>/experiences/ │<br />
│ /api/characters/<id>/skills/ │<br />
│ /api/characters/<id>/resources/ │<br />
│ /api/characters/<id>/marks/ │<br />
│ /api/characters/<id>/characters/ │<br />
│ /api/characters/<id>/pending-changes/ │<br />
│ /api/prompts/ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django ORM / SQLite │<br />
│ Character · Memory · Experience · Skill │<br />
│ Resource · Mark · GameCharacter · Prompt │<br />
│ PendingChange · GameStateSnapshot │<br />
└─────────────────────────────────────────────────┘<br />
</pre><br />
<br />
== Backend ==<br />
<br />
=== Django Apps ===<br />
<br />
The project is organised into three Django apps plus a settings module:<br />
<br />
{| class="wikitable"<br />
|-<br />
! App !! Purpose<br />
|-<br />
| <code>vampire</code> || Core domain models: Character, Memory, Experience, Skill, Resource, Mark, GameCharacter, Prompt, PendingChange, GameStateSnapshot<br />
|-<br />
| <code>tyov_api</code> || REST API layer: serialisers, viewsets, URL routing, permissions, middleware<br />
|-<br />
| <code>authentication</code> || JWT-based login and token verification endpoints<br />
|-<br />
| <code>tyov_backend</code> || Django project settings, URL root, WSGI/ASGI configuration<br />
|}<br />
<br />
=== Data Models ===<br />
<br />
==== Character ====<br />
<br />
The central model, owned by a Django <code>User</code> via a ForeignKey:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Field !! Type !! Description<br />
|-<br />
| <code>name</code> || CharField(200) || Current name of the vampire<br />
|-<br />
| <code>description</code> || TextField || Background/appearance description<br />
|-<br />
| <code>image</code> || ImageField || Optional character portrait<br />
|-<br />
| <code>current_prompt</code> || CharField(10) || ID of the current prompt (e.g. "17a")<br />
|-<br />
| <code>last_dice_roll</code> || JSONField || Stores D10, D6, and result of the last roll<br />
|-<br />
| <code>visited_prompts</code> || JSONField(list) || List of all prompt IDs visited in order<br />
|-<br />
| <code>memory_slots_lost</code> || IntegerField || Permanent memory slot reductions<br />
|-<br />
| <code>memory_slots_gained</code> || IntegerField || Permanent memory slot increases<br />
|-<br />
| <code>creation_step</code> || IntegerField(1–6) || Tracks progress through the creation wizard<br />
|-<br />
| <code>is_creation_complete</code> || BooleanField || True when all six creation steps are finished<br />
|-<br />
| <code>creation_data</code> || JSONField || Temporary storage during creation<br />
|-<br />
| <code>epilogue</code> || TextField || Player's final reflection (set at game end)<br />
|-<br />
| <code>is_completed</code> || BooleanField || Whether the story has ended<br />
|-<br />
| <code>completed_at</code> || DateTimeField || Timestamp of story completion<br />
|}<br />
<br />
==== Memory ====<br />
<br />
A memory belongs to a Character and holds up to 3 Experiences:<br />
<br />
* <code>title</code> – descriptive name (unique per character)<br />
* <code>in_diary</code> – whether the memory is stored in the diary<br />
* <code>is_lost</code> – whether the memory has been forgotten<br />
<br />
==== Experience ====<br />
<br />
An individual narrative entry within a Memory:<br />
<br />
* <code>title</code> – optional short description<br />
* <code>content</code> – the narrative text<br />
* <code>prompt_id</code> – which prompt generated this experience<br />
* <code>date_info</code> – temporal context (e.g. "Winter, 431 CE")<br />
<br />
==== Skill ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>status</code> – one of <code>normal</code>, <code>checked</code>, or <code>lost</code><br />
<br />
==== Resource ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>resource_type</code> – <code>portable</code> or <code>stationary</code><br />
* <code>is_diary</code> – flags the special diary resource (constrained to one active diary per character)<br />
* <code>is_lost</code><br />
<br />
==== Mark ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>is_lost</code><br />
<br />
==== GameCharacter ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>character_type</code> – <code>mortal</code> or <code>immortal</code><br />
* <code>relationship</code> – e.g. friend, rival, mentor, love, enemy, neutral<br />
* <code>is_lost</code><br />
<br />
==== Prompt ====<br />
<br />
* <code>prompt_id</code> – e.g. "17a", "32b"<br />
* <code>number</code>, <code>variation</code> – parsed components for sorting<br />
* <code>content</code> – the scenario text<br />
* <code>rules</code> – special mechanics as comma-separated tokens (e.g. <code>no_experience, allow_name_change</code>)<br />
<br />
==== PendingChange ====<br />
<br />
Temporary storage for changes before they are atomically committed on "Continue":<br />
<br />
* <code>change_type</code> – experience, memory, skill, resource, mark, or character<br />
* <code>change_data</code> – JSON payload of the change<br />
<br />
==== GameStateSnapshot (Audit Trail) ====<br />
<br />
Automatically created each turn to record the complete game state:<br />
<br />
* <code>turn_number</code> – sequential, starting from 1<br />
* <code>prompt_id</code> / <code>next_prompt_id</code> – transition<br />
* <code>dice_roll</code> – raw dice data<br />
* <code>game_state</code> – full JSON snapshot of all memories, skills, resources, etc.<br />
* <code>changes_applied</code> – JSON array of pending changes that were committed<br />
* <code>created_at</code> – timestamp<br />
<br />
=== API Endpoints ===<br />
<br />
All endpoints require JWT authentication (except login).<br />
<br />
==== Authentication ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| POST || <code>/api/auth/login/</code> || Authenticate with username/password; returns JWT token<br />
|-<br />
| POST || <code>/api/auth/verify/</code> || Verify current token and return user info<br />
|}<br />
<br />
Login is rate-limited to 5 requests per minute per IP.<br />
<br />
==== Characters ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/characters/</code> || List all characters for the authenticated user<br />
|-<br />
| POST || <code>/api/characters/</code> || Create a new character<br />
|-<br />
| GET || <code>/api/characters/{id}/</code> || Retrieve full character detail (prefetched relations)<br />
|-<br />
| PUT/PATCH || <code>/api/characters/{id}/</code> || Update character fields<br />
|-<br />
| DELETE || <code>/api/characters/{id}/</code> || Delete a character<br />
|-<br />
| GET || <code>/api/characters/{id}/game_state/</code> || Complete game state including prompt, validation, dice info<br />
|-<br />
| POST || <code>/api/characters/{id}/roll_dice/</code> || Roll D10 − D6 and store the result<br />
|-<br />
| POST || <code>/api/characters/{id}/continue_story/</code> || Validate, commit pending changes, advance to next prompt<br />
|-<br />
| GET || <code>/api/characters/{id}/audit_trail/</code> || View turn-by-turn audit history<br />
|-<br />
| GET || <code>/api/characters/{id}/game-state-changes/</code> || Timeline of state changes between turns<br />
|}<br />
<br />
==== Nested Character Resources ====<br />
<br />
For each character, full CRUD is available on:<br />
<br />
* <code>/api/characters/{id}/memories/</code> (plus <code>move_to_diary</code> and <code>restore_lost_memory</code> actions)<br />
* <code>/api/characters/{id}/experiences/</code><br />
* <code>/api/characters/{id}/skills/</code><br />
* <code>/api/characters/{id}/resources/</code><br />
* <code>/api/characters/{id}/marks/</code><br />
* <code>/api/characters/{id}/characters/</code> (known NPCs)<br />
* <code>/api/characters/{id}/pending-changes/</code><br />
<br />
==== Prompts ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/prompts/</code> || List all game prompts<br />
|-<br />
| GET || <code>/api/prompts/{prompt_id}/</code> || Retrieve a single prompt by ID<br />
|}<br />
<br />
=== Permissions and Security ===<br />
<br />
* All character data is scoped to the authenticated user via <code>IsCharacterOwner</code> permission.<br />
* JWT tokens are sent as <code>Authorization: Bearer {token}</code> headers.<br />
* The login endpoint is throttled (5/minute) to prevent brute-force attacks.<br />
* All pending changes are processed inside a database '''transaction''' to guarantee atomicity.<br />
* CORS headers are configured via <code>django-cors-headers</code>.<br />
<br />
== Frontend ==<br />
<br />
=== Views (Pages) ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! View !! Route !! Description<br />
|-<br />
| '''LoginView''' || <code>/login</code> || Authentication form; redirects authenticated users to home<br />
|-<br />
| '''HomeView''' || <code>/</code> || Dashboard showing all active characters in a card grid<br />
|-<br />
| '''CharacterCreationView''' || <code>/character-creation/:id</code> || Six-step creation wizard<br />
|-<br />
| '''GameView''' || <code>/game/:characterId</code> || Main game loop: prompt display, experience form, dice rolling, entity management, memory display<br />
|-<br />
| '''GameEndedView''' || <code>/game/:characterId/ended</code> || End-of-story screen with statistics and epilogue<br />
|-<br />
| '''RecordsView''' || <code>/records</code> || Archive of current and completed characters<br />
|-<br />
| '''StoryView''' || <code>/story/:characterId</code> || Narrative timeline with experience history, character stats sidebar, and epilogue<br />
|}<br />
<br />
All routes except <code>/login</code> require authentication. The router guard redirects unauthenticated users.<br />
<br />
=== Key Components ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Component !! Purpose<br />
|-<br />
| '''PromptSection''' || Displays the current prompt text, special rules, and dice roll results<br />
|-<br />
| '''ExperienceForm''' || Form for writing new experiences with title, date, content, and memory selection<br />
|-<br />
| '''MemoriesDisplay''' || Shows active, diary, and lost memories with experience counts; includes move-to-diary, delete, and restore actions<br />
|-<br />
| '''GameDataSection''' || Reusable list for skills, resources, or marks with add/edit/delete controls<br />
|-<br />
| '''CharactersSection''' || Grid of known NPCs with type badges and edit/delete<br />
|-<br />
| '''EntityCreationWindow''' || Draggable modal for creating/editing skills, resources, marks<br />
|-<br />
| '''CharacterCreationWindow''' || Draggable modal for creating/editing NPC characters<br />
|-<br />
| '''ExperienceEditWindow''' || Window for editing existing experience text<br />
|-<br />
| '''DiaryCreationModal''' || Modal for creating a diary resource and moving a memory into it<br />
|-<br />
| '''ConfirmationDialog''' || Generic confirmation dialog for destructive actions<br />
|-<br />
| '''ValidationWarning''' || Displays validation errors when game rules are not satisfied<br />
|}<br />
<br />
=== State Management (Pinia) ===<br />
<br />
Four Pinia stores manage application state:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Store !! Responsibility<br />
|-<br />
| '''auth''' || JWT token, user object, login/logout, token expiry handling<br />
|-<br />
| '''game''' || Characters list, current character, game state, all CRUD actions for entities, dice rolling, story continuation<br />
|-<br />
| '''characterCreation''' || Multi-step wizard data, initial character creation<br />
|-<br />
| '''theme''' || Dark/light mode toggle with localStorage persistence<br />
|}<br />
<br />
=== API Service Layer ===<br />
<br />
* '''<code>api.ts</code>''' – Axios instance with base URL auto-detection (development vs. production), request interceptor for JWT headers, response interceptor for 401/token-expiry handling.<br />
* '''<code>gameService.ts</code>''' – All API call methods: authentication, character CRUD, dice rolling, story continuation, memory/experience/skill/resource/mark/character management.<br />
* '''<code>entityService.ts</code>''' – Generic <code>EntityService</code> class instantiated for skills, resources, marks, and characters for DRY CRUD operations.<br />
<br />
=== Composables ===<br />
<br />
Vue composables encapsulate reusable business logic:<br />
<br />
* '''<code>useGameData()</code>''' – Computed properties derived from the game store (current character, memories, skills, resources, etc.)<br />
* '''<code>useExperienceForm()</code>''' – Form state, validation, memory selection, and reset logic<br />
* '''<code>useEntityManagement()</code>''' – Generic CRUD operations with optional confirmation dialogs<br />
* '''<code>useSkillManagement()</code>''', '''<code>useResourceManagement()</code>''', '''<code>useMarkManagement()</code>''', '''<code>useMemoryManagement()</code>''' – Specialised wrappers<br />
* '''<code>useConfirmationDialog()</code>''' – Promise-based modal confirmation<br />
* '''<code>useMemoryDisplay()</code>''' – Display logic for memories including pending-change awareness<br />
* '''<code>useExperienceDisplay()</code>''' – Markdown rendering for experience content<br />
* '''<code>usePendingChangesDisplay()</code>''' – Badge rendering for undo-able pending changes<br />
<br />
== Audit Trail ==<br />
<br />
The application includes an automatic audit trail that captures the complete game state every time the player advances to a new prompt.<br />
<br />
Each '''GameStateSnapshot''' records:<br />
<br />
* The turn number (sequential from 1)<br />
* The prompt transition (e.g. 36a → 34a)<br />
* The dice roll<br />
* A complete JSON snapshot of all memories, skills, resources, marks, and known characters<br />
* All pending changes that were committed<br />
<br />
The audit trail is accessible via:<br />
<br />
* '''API''': <code>GET /api/characters/{id}/audit_trail/</code> with optional <code>?turn=N</code> and <code>?limit=N</code> parameters<br />
* '''Management command''': <code>python manage.py view_audit_trail {id} [--summary] [--turn N] [--export file.json]</code><br />
* '''Timeline API''': <code>GET /api/characters/{id}/game-state-changes/</code> for a structured timeline of all state changes<br />
<br />
== Deployment ==<br />
<br />
=== Local Development ===<br />
<br />
<pre><br />
.\startup.ps1<br />
</pre><br />
<br />
This script creates a virtual environment, installs dependencies, runs migrations, and starts both the Django backend (<code>http://localhost:8000</code>) and the Vue dev server (<code>http://localhost:5173</code>).<br />
<br />
=== Production ===<br />
<br />
* Set <code>DJANGO_ENV=production</code><br />
* Build the frontend: <code>cd frontend && npm run build</code><br />
* Serve with Gunicorn behind a reverse proxy<br />
* Static files are collected into the <code>static/</code> directory<br />
* The production frontend points to <code>https://tyov.yusupov.cloud</code><br />
<br />
== Example: A Finished Character ==<br />
<br />
The following is an example of a character from an actual playthrough stored in the application database. It demonstrates how the game's mechanics play out over an extended narrative.<br />
<br />
=== Karmiš (formerly Ekurzu / Naram) ===<br />
<br />
'''Description:''' Naram was a temple scribe in the ancient city of Mari: meticulous, observant, and deeply entangled in the political and spiritual life of the city. His life was shaped by clay tablets, omens, and whispered secrets carried through palace corridors and temple courtyards. Behind his calm demeanor lies a mind constantly at work—recording, interpreting, and surviving.<br />
<br />
'''Prompts visited:''' 34 prompts across variations, including: 1a, 4a, 11a–c, 12a, 17a, 20a, 24a, 25a, 32a–b, 34a–36a, 37a–41c, 43a–c, 47a, 52a, 57a, 64a, 66a, 68a, 71a, 73a.<br />
<br />
'''Final prompt:''' 73a<br />
<br />
'''Memory slots lost:''' 1 · '''Memory slots gained:''' 1 (net effect: standard 5-memory limit)<br />
<br />
==== Epilogue ====<br />
<br />
<blockquote><br />
He has not died. Let me say that plainly. There will be no grave. He is alive, but quietly, deliberately, and utterly outside your reach.<br />
<br />
When I first met him, I did not understand what he was. He wore his years like dust on old vellum—thin, barely visible, but ever present. [...] Over time, I became his mirror, then his partner, and finally his historian.<br />
<br />
But someone has to begin the telling. Someone has to place the first stone. So this book begins in a house of quiet gardens and low ceilings, where he writes in the mornings and feeds only when he must. [...]<br />
<br />
Just a man who remembered too much, for too long. And chose, in the end, ''peace''.<br />
<br />
— ''Mirelde''<br />
</blockquote><br />
<br />
==== Statistics ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Metric !! Count<br />
|-<br />
| Total memories || 16<br />
|-<br />
| Active memories || 5<br />
|-<br />
| Diary memories || 3<br />
|-<br />
| Lost (forgotten) memories || 8<br />
|-<br />
| Total experiences || 37<br />
|-<br />
| Skills || 11 (3 lost during play)<br />
|-<br />
| Resources || 10 (6 lost during play)<br />
|-<br />
| Marks || 2<br />
|-<br />
| Known characters || 11 (6 lost during play)<br />
|}<br />
<br />
==== Active Memories (at end of game) ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Memory Title !! Location !! Experiences<br />
|-<br />
| Memory 1 || Active || "Mortal life" (Initial), "The Name Given in Ash" (24a)<br />
|-<br />
| The Thorn and the Quill || Active || 1 experience (35a)<br />
|-<br />
| The Light That Does Not Burn || Active || "The Dawn at Mirelde's Fire" (52a), "The Dust in the Foundation" (57a)<br />
|-<br />
| We Were Not Counted Among the Cargo || Active || "The Bellies of Ships and Men" (64a), "Ink Without Meaning" (66a)<br />
|-<br />
| Echoes Before the Self Was Named || Active || "The Weight in the Smoke" (71a), "The Clay That Knew My Name" (68a)<br />
|}<br />
<br />
==== Diary Memories ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Memory Title !! Experiences<br />
|-<br />
| The Hill That Waits || "The Hollow Beneath the Cairn" (40a), "The Ring Beneath the Clay" (43c), "The Face Returned Through Time" (44a)<br />
|-<br />
| Ash of the Ledger || "The Last Ledger Vanishes" (38a), "The Fog Beneath Names" (39b), "The Weight of Unspoken Words" (34a)<br />
|-<br />
| The Fever-Ledger || "The Illness in Karkheda" (36a), "The Name That Returns in Ash" (41c), "The Echo That Cannot Translate" (47a)<br />
|}<br />
<br />
==== Lost Memories ====<br />
<br />
Eight memories were forgotten over the course of the game, including "The Forged Omen" (Memory 2), "Hessa's Last Message" (Memory 3), "Duel of Stars and Signs" (Memory 4), "The Turning", "The Name That Cannot Burn", "The Blood Between Accusations", "Trade Beneath Empire", and "What Was Meant to Last". These losses illustrate the game's core mechanic: as new experiences accumulate, the vampire is forced to sacrifice older memories, creating a poignant sense of identity erosion across the centuries.<br />
<br />
==== Skills ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Skill !! Status !! Description (excerpt)<br />
|-<br />
| Ash-Tongue || {{Checked}} || "I speak in soot and suggestion, in the cracks between laws."<br />
|-<br />
| Bloodthirsty || {{Lost}} || "The scent of mortal blood calls to me like a hymn in the dark."<br />
|-<br />
| Ceremonial Composure || {{Checked}} || "In the presence of gods or kings, my face is unreadable."<br />
|-<br />
| Decipher Ancient Texts || {{Lost}} || "I can read languages long dead and spot forgeries."<br />
|-<br />
| I Control the Beast || {{Lost}} || "When the thirst rises, I do not flinch. I meet the monster's gaze."<br />
|-<br />
| Ledger Without End || Normal || "Born from the quiet rituals of inventory and account."<br />
|-<br />
| Physick of the Pale Vein || Normal || "I feed gently, beneath the guise of care."<br />
|-<br />
| Remain in Unknowing || {{Checked}} || "I do not flee the edges of memory."<br />
|-<br />
| Silent Cartography || {{Checked}} || "I trace the unseen paths between people, places, and power."<br />
|-<br />
| Snare and Stillness || {{Checked}} || "I move with silence that makes mortals forget they heard me."<br />
|-<br />
| Tongue of the Unnamed || Normal || "I no longer understand the languages of my past, but I wear the sounds of others like masks."<br />
|}<br />
<br />
==== Resources ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Resource !! Type !! Status !! Notes<br />
|-<br />
| Kept Against Forgetting || Portable / '''Diary''' || Active || The character's diary; written with Mirelde<br />
|-<br />
| Tablet Bearing My Name || Portable || Active || A clay tablet from the ancient past, rediscovered<br />
|-<br />
| The Margins of Manifest || Portable || Active || A cipher-folio cataloguing names of the enslaved<br />
|-<br />
| Burrowed Sanctum || Portable || Lost || An earthen chamber beneath a forgotten altar<br />
|-<br />
| Chamber of Whispers || Stationary || Lost || A hidden storeroom beneath the temple of Ishtar<br />
|-<br />
| Clay Tablets and Reed Stylus || Portable || Lost || Writing implements used by instinct, not understanding<br />
|-<br />
| Hidden Archive Tablet || Portable || Lost || A tablet inscribed with dynasty-breaking truths<br />
|-<br />
| The Monastery Diary || Portable / Diary || Lost || A former diary, lost when the monastery fell<br />
|-<br />
| The Silent Authority || Portable || Lost || A carved seal whose symbols can no longer be read<br />
|-<br />
| The Walls of Forgetting || Stationary / Diary || Lost || Memory carvings in five scripts beneath a forgotten shrine<br />
|}<br />
<br />
==== Known Characters ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Name !! Type !! Relationship !! Status<br />
|-<br />
| Ashurban the Veiled || Immortal || Neutral || Active<br />
|-<br />
| Mirelde of Bracha || Immortal || Friend || Active<br />
|-<br />
| The One Who Does Not Answer || Mortal || Neutral || Active<br />
|-<br />
| Thoöni (spectral) || Immortal || Neutral || Active<br />
|-<br />
| Belatu || Mortal || Rival || Lost<br />
|-<br />
| Ennatum || Mortal || Friend || Lost<br />
|-<br />
| Hessa || Mortal || Love || Lost<br />
|-<br />
| Ibbi-Zamri || Mortal || Mentor || Lost<br />
|-<br />
| Mekha || Mortal || Enemy || Lost<br />
|-<br />
| Pelagon || Mortal || Enemy || Lost<br />
|-<br />
| Thoöni (scholar) || Mortal || Friend || Lost<br />
|}<br />
<br />
==== Marks ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Mark !! Description<br />
|-<br />
| The Unblinking Eye || An ancient eye-like scar below the collarbone; burns faintly in the presence of lies<br />
|-<br />
| The Gesture Forbidden || An involuntary three-fingered gesture of silence, often mistaken for mockery<br />
|}<br />
<br />
==== Example Experience: "The Bellies of Ships and Men" (Prompt 64a) ====<br />
<br />
<blockquote><br />
They arrived in numbers too vast to count—pressed between barrels, chained to holds slick with piss and seawater, branded, sick, broken. And the sailors were not much better.<br />
<br />
The ships would come in [...]<br />
</blockquote><br />
<br />
''Date: around 1510 CE''<br />
<br />
This experience is part of the memory "We Were Not Counted Among the Cargo", illustrating the vampire's witness to the Atlantic slave trade—one of many historical eras the character passes through during a millennium-spanning story.<br />
<br />
== Testing ==<br />
<br />
=== Backend ===<br />
<br />
Tests are run with '''pytest''' and '''pytest-django''':<br />
<br />
<pre><br />
pytest<br />
</pre><br />
<br />
Test files include:<br />
* <code>vampire/test_models.py</code> – model unit tests<br />
* <code>tyov_api/test_api.py</code> – API endpoint integration tests<br />
* <code>tyov_api/test_models.py</code> – API model tests<br />
* <code>authentication/test_views.py</code> – authentication tests<br />
<br />
=== Frontend ===<br />
<br />
End-to-end tests use '''Playwright''':<br />
<br />
<pre><br />
cd frontend<br />
npx playwright test<br />
</pre><br />
<br />
Test specs include:<br />
* <code>e2e/character-creation-workflow.spec.ts</code> – character creation wizard<br />
* <code>e2e/tyov-game.spec.ts</code> – game loop testing<br />
* <code>e2e/vue.spec.ts</code> – general Vue component tests<br />
<br />
== See Also ==<br />
<br />
* ''Thousand Year Old Vampire'' by Tim Hutchings – the original tabletop game<br />
* [[Django (web framework)]]<br />
* [[Vue.js]]<br />
* [[Single-page application]]<br />
<br />
== References ==<br />
<br />
{{Reflist}}<br />
<br />
[[Category:Web applications]]<br />
[[Category:Role-playing video games]]<br />
[[Category:Django (web framework) applications]]<br />
[[Category:Vue.js applications]]<br />
[[Category:Solo role-playing games]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Thousand_Year_Old_Vampire&diff=384Thousand Year Old Vampire2026-04-12T11:15:40Z<p>Mvuijlst: Created page with "{{Infobox | 01_name = Thousand Year Old Vampire – Web Helper | 02_logo = | 03_developer = Michel Vuijlsteke | 04_programming language = Python (Django 5), TypeScript (Vue 3) | 05_operating system = Cross-platform (Web) | 06_genre = Solo RPG Digital Companion | 07_license = custom | 08_website = <code>https://tyov.yusupov.cloud</code> }} '''Thousand Year Old Vampire – Web Helper''' ('''TYOV-Web''') is a modern web-based implementation of the solo tabletop role-playi..."</p>
<hr />
<div>{{Infobox <br />
| 01_name = Thousand Year Old Vampire – Web Helper<br />
| 02_logo =<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_programming language = Python (Django 5), TypeScript (Vue 3)<br />
| 05_operating system = Cross-platform (Web)<br />
| 06_genre = Solo RPG Digital Companion<br />
| 07_license = custom<br />
| 08_website = <code>https://tyov.yusupov.cloud</code><br />
}}<br />
<br />
'''Thousand Year Old Vampire – Web Helper''' ('''TYOV-Web''') is a modern web-based implementation of the solo tabletop role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. The application digitises the game's complex mechanics of memory, experience, and character development, allowing players to create and guide a vampire character across centuries of unlife through an interactive browser interface. The backend is built with '''Django 5''' and '''Django REST Framework'''; the frontend is a '''Vue 3''' single-page application.<br />
<br />
== Overview ==<br />
<br />
''Thousand Year Old Vampire'' is a solo storytelling RPG in which a player creates a vampire character and guides it through an increasingly fragmented existence spanning hundreds or thousands of years. The central tension lies in the vampire's deteriorating memory: as an immortal being it accumulates experiences, but its ancient mind can only retain a limited number of memories at any time. Players must constantly choose what to remember and what to forget.<br />
<br />
TYOV-Web fully implements the game's rules—character creation, dice-driven prompt navigation, memory management, diary storage, skills, resources, marks, known characters, and game-ending conditions—in a reactive web interface with persistent server-side storage and a complete audit trail.<br />
<br />
== Game Rules ==<br />
<br />
=== Core Concept ===<br />
<br />
The player creates a vampire and progresses through numbered '''prompts''' (story scenarios). Each prompt asks the player to narrate what happens to the vampire during a particular era. The game is non-linear: dice rolls determine which prompt to visit next, and most prompts have multiple '''variations''' (A, B, C) to prevent repetition.<br />
<br />
=== Character Creation ===<br />
<br />
Character creation follows a guided six-step wizard:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Step !! Description<br />
|-<br />
| 1. Mortal Life || Establish the vampire's name, background, and mortal existence<br />
|-<br />
| 2. Mortal Characters || Define 2–4 NPCs from the vampire's human life (friends, mentors, rivals, lovers)<br />
|-<br />
| 3. Skills || Choose 2–3 starting skills representing mortal expertise<br />
|-<br />
| 4. Resources || Select initial possessions and locations<br />
|-<br />
| 5. Combination Experience || Write a pivotal mortal-life experience that ties characters, skills, and resources together<br />
|-<br />
| 6. The Turning || Narrate how and why the character was turned into a vampire<br />
|}<br />
<br />
=== Memory System ===<br />
<br />
The memory system is the heart of the game:<br />
<br />
* A character may hold a maximum of '''5 active memories''' (adjustable by prompt rules and permanent effects).<br />
* Each memory can contain up to '''3 experiences''' (individual narrative entries).<br />
* When the limit is exceeded, the player must '''forget''' (permanently lose) a memory, or '''move''' one to a '''diary''' (if the character possesses one).<br />
* A '''diary''' is a special resource that stores up to '''4 additional memories''' outside the active limit.<br />
* If the diary resource is lost, all memories stored in it are also lost.<br />
* Some prompts grant or remove permanent memory slots (<code>memory_slot_gain</code>, <code>memory_slot_loss</code>).<br />
<br />
=== Dice Rolling and Prompt Navigation ===<br />
<br />
Each turn the player rolls two dice:<br />
<br />
* '''D10''' (1–10) minus '''D6''' (1–6) = result (range: −5 to +9).<br />
* A '''positive''' result moves forward that many prompts.<br />
* A '''negative''' result moves backward.<br />
* A result of '''zero''' stays at the current prompt number but selects the next unused variation.<br />
<br />
Variations are visited in order A → B → C. If all variations of a prompt have been used, the system finds the next available variation in prompt order.<br />
<br />
=== Turn Structure ===<br />
<br />
Each game turn follows this sequence:<br />
<br />
# '''Prompt Presentation''' – The current prompt text and any special rules are displayed.<br />
# '''Dice Roll''' – The player rolls D10 − D6 to determine the next prompt.<br />
# '''Experience Creation''' – The player writes at least one narrative experience for the current prompt.<br />
# '''Character Updates''' – Skills, resources, marks, and known characters may be added, edited, checked, or removed.<br />
# '''Memory Management''' – The player resolves any memory overflow (forget or move to diary).<br />
# '''Validation''' – The system verifies all rules are satisfied (at least one experience added, memory limits respected, etc.).<br />
# '''Continue''' – All pending changes are atomically committed and the game advances to the next prompt.<br />
<br />
=== Character Attributes ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Attribute !! Description<br />
|-<br />
| '''Skills''' || Learned abilities; can be ''normal'' (latent), ''checked'' (used/active), or ''lost'' (permanently removed).<br />
|-<br />
| '''Resources''' || Possessions or locations; typed as ''portable'' or ''stationary''. One resource may be flagged as a ''diary''.<br />
|-<br />
| '''Marks''' || Physical or psychological scars that accumulate over time.<br />
|-<br />
| '''Known Characters''' || NPCs the vampire has encountered; typed as ''mortal'' or ''immortal''; may be lost (dead, vanished, etc.).<br />
|}<br />
<br />
=== Special Prompt Rules ===<br />
<br />
Certain prompts carry special mechanics encoded as rules:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Rule !! Effect<br />
|-<br />
| <code>no_experience</code> || Experience creation is disabled for this turn<br />
|-<br />
| <code>allow_name_change</code> || The player may change the vampire's name<br />
|-<br />
| <code>memory_modification</code> || The player may edit the text of existing experiences<br />
|-<br />
| <code>memory_slot_loss</code> || Permanent reduction of memory capacity by 1<br />
|-<br />
| <code>memory_slot_gain</code> || Permanent increase of memory capacity by 1<br />
|-<br />
| <code>game_over</code> || The game ends; the player writes an epilogue<br />
|}<br />
<br />
=== Game Ending ===<br />
<br />
The game ends when the player reaches a prompt with the <code>game_over</code> rule (or under other conditions defined by the original game). The player writes an '''epilogue'''—a final reflection on the vampire's story—and the character is archived. A statistics summary shows prompt count, memories, experiences, skills, resources, marks, and characters accumulated during the playthrough.<br />
<br />
== Architecture ==<br />
<br />
=== Technology Stack ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Layer !! Technology !! Version<br />
|-<br />
| Backend framework || Django || 5.0.6<br />
|-<br />
| REST API || Django REST Framework || 3.15.1<br />
|-<br />
| Authentication || Simple JWT (custom) || 5.3.0<br />
|-<br />
| CORS || django-cors-headers || 4.3.1<br />
|-<br />
| Image handling || Pillow || 11.3.0<br />
|-<br />
| Production server || Gunicorn || 21.2.0<br />
|-<br />
| Frontend framework || Vue.js || 3.5<br />
|-<br />
| State management || Pinia || 3.0<br />
|-<br />
| Routing || Vue Router || 4.5<br />
|-<br />
| HTTP client || Axios || 1.10<br />
|-<br />
| CSS framework || Bootstrap || 5.3<br />
|-<br />
| Build tool || Vite || 7.0<br />
|-<br />
| Language || TypeScript || 5.8<br />
|-<br />
| Testing (backend) || pytest + pytest-django || 8.0 / 4.8<br />
|-<br />
| Testing (frontend) || Playwright || 1.53<br />
|}<br />
<br />
=== High-Level Diagram ===<br />
<br />
<pre><br />
┌─────────────────────────────────────────────────┐<br />
│ Vue 3 SPA (TypeScript) │<br />
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│<br />
│ │ Views │ │Components│ │ Pinia Stores ││<br />
│ │ (7 pages)│ │ (14+) │ │ auth/game/theme/ ││<br />
│ │ │ │ │ │ characterCreation ││<br />
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘│<br />
│ └─────────────┴────────────────┘ │<br />
│ │ Axios │<br />
│ ▼ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django REST API │<br />
│ /api/auth/login /api/auth/verify │<br />
│ /api/characters/ (CRUD + game_state, │<br />
│ roll_dice, continue_story, audit_trail) │<br />
│ /api/characters/<id>/memories/ │<br />
│ /api/characters/<id>/experiences/ │<br />
│ /api/characters/<id>/skills/ │<br />
│ /api/characters/<id>/resources/ │<br />
│ /api/characters/<id>/marks/ │<br />
│ /api/characters/<id>/characters/ │<br />
│ /api/characters/<id>/pending-changes/ │<br />
│ /api/prompts/ │<br />
├─────────────────────────────────────────────────┤<br />
│ Django ORM / SQLite │<br />
│ Character · Memory · Experience · Skill │<br />
│ Resource · Mark · GameCharacter · Prompt │<br />
│ PendingChange · GameStateSnapshot │<br />
└─────────────────────────────────────────────────┘<br />
</pre><br />
<br />
== Backend ==<br />
<br />
=== Django Apps ===<br />
<br />
The project is organised into three Django apps plus a settings module:<br />
<br />
{| class="wikitable"<br />
|-<br />
! App !! Purpose<br />
|-<br />
| <code>vampire</code> || Core domain models: Character, Memory, Experience, Skill, Resource, Mark, GameCharacter, Prompt, PendingChange, GameStateSnapshot<br />
|-<br />
| <code>tyov_api</code> || REST API layer: serialisers, viewsets, URL routing, permissions, middleware<br />
|-<br />
| <code>authentication</code> || JWT-based login and token verification endpoints<br />
|-<br />
| <code>tyov_backend</code> || Django project settings, URL root, WSGI/ASGI configuration<br />
|}<br />
<br />
=== Data Models ===<br />
<br />
==== Character ====<br />
<br />
The central model, owned by a Django <code>User</code> via a ForeignKey:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Field !! Type !! Description<br />
|-<br />
| <code>name</code> || CharField(200) || Current name of the vampire<br />
|-<br />
| <code>description</code> || TextField || Background/appearance description<br />
|-<br />
| <code>image</code> || ImageField || Optional character portrait<br />
|-<br />
| <code>current_prompt</code> || CharField(10) || ID of the current prompt (e.g. "17a")<br />
|-<br />
| <code>last_dice_roll</code> || JSONField || Stores D10, D6, and result of the last roll<br />
|-<br />
| <code>visited_prompts</code> || JSONField(list) || List of all prompt IDs visited in order<br />
|-<br />
| <code>memory_slots_lost</code> || IntegerField || Permanent memory slot reductions<br />
|-<br />
| <code>memory_slots_gained</code> || IntegerField || Permanent memory slot increases<br />
|-<br />
| <code>creation_step</code> || IntegerField(1–6) || Tracks progress through the creation wizard<br />
|-<br />
| <code>is_creation_complete</code> || BooleanField || True when all six creation steps are finished<br />
|-<br />
| <code>creation_data</code> || JSONField || Temporary storage during creation<br />
|-<br />
| <code>epilogue</code> || TextField || Player's final reflection (set at game end)<br />
|-<br />
| <code>is_completed</code> || BooleanField || Whether the story has ended<br />
|-<br />
| <code>completed_at</code> || DateTimeField || Timestamp of story completion<br />
|}<br />
<br />
==== Memory ====<br />
<br />
A memory belongs to a Character and holds up to 3 Experiences:<br />
<br />
* <code>title</code> – descriptive name (unique per character)<br />
* <code>in_diary</code> – whether the memory is stored in the diary<br />
* <code>is_lost</code> – whether the memory has been forgotten<br />
<br />
==== Experience ====<br />
<br />
An individual narrative entry within a Memory:<br />
<br />
* <code>title</code> – optional short description<br />
* <code>content</code> – the narrative text<br />
* <code>prompt_id</code> – which prompt generated this experience<br />
* <code>date_info</code> – temporal context (e.g. "Winter, 431 CE")<br />
<br />
==== Skill ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>status</code> – one of <code>normal</code>, <code>checked</code>, or <code>lost</code><br />
<br />
==== Resource ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>resource_type</code> – <code>portable</code> or <code>stationary</code><br />
* <code>is_diary</code> – flags the special diary resource (constrained to one active diary per character)<br />
* <code>is_lost</code><br />
<br />
==== Mark ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>is_lost</code><br />
<br />
==== GameCharacter ====<br />
<br />
* <code>name</code>, <code>description</code><br />
* <code>character_type</code> – <code>mortal</code> or <code>immortal</code><br />
* <code>relationship</code> – e.g. friend, rival, mentor, love, enemy, neutral<br />
* <code>is_lost</code><br />
<br />
==== Prompt ====<br />
<br />
* <code>prompt_id</code> – e.g. "17a", "32b"<br />
* <code>number</code>, <code>variation</code> – parsed components for sorting<br />
* <code>content</code> – the scenario text<br />
* <code>rules</code> – special mechanics as comma-separated tokens (e.g. <code>no_experience, allow_name_change</code>)<br />
<br />
==== PendingChange ====<br />
<br />
Temporary storage for changes before they are atomically committed on "Continue":<br />
<br />
* <code>change_type</code> – experience, memory, skill, resource, mark, or character<br />
* <code>change_data</code> – JSON payload of the change<br />
<br />
==== GameStateSnapshot (Audit Trail) ====<br />
<br />
Automatically created each turn to record the complete game state:<br />
<br />
* <code>turn_number</code> – sequential, starting from 1<br />
* <code>prompt_id</code> / <code>next_prompt_id</code> – transition<br />
* <code>dice_roll</code> – raw dice data<br />
* <code>game_state</code> – full JSON snapshot of all memories, skills, resources, etc.<br />
* <code>changes_applied</code> – JSON array of pending changes that were committed<br />
* <code>created_at</code> – timestamp<br />
<br />
=== API Endpoints ===<br />
<br />
All endpoints require JWT authentication (except login).<br />
<br />
==== Authentication ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| POST || <code>/api/auth/login/</code> || Authenticate with username/password; returns JWT token<br />
|-<br />
| POST || <code>/api/auth/verify/</code> || Verify current token and return user info<br />
|}<br />
<br />
Login is rate-limited to 5 requests per minute per IP.<br />
<br />
==== Characters ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/characters/</code> || List all characters for the authenticated user<br />
|-<br />
| POST || <code>/api/characters/</code> || Create a new character<br />
|-<br />
| GET || <code>/api/characters/{id}/</code> || Retrieve full character detail (prefetched relations)<br />
|-<br />
| PUT/PATCH || <code>/api/characters/{id}/</code> || Update character fields<br />
|-<br />
| DELETE || <code>/api/characters/{id}/</code> || Delete a character<br />
|-<br />
| GET || <code>/api/characters/{id}/game_state/</code> || Complete game state including prompt, validation, dice info<br />
|-<br />
| POST || <code>/api/characters/{id}/roll_dice/</code> || Roll D10 − D6 and store the result<br />
|-<br />
| POST || <code>/api/characters/{id}/continue_story/</code> || Validate, commit pending changes, advance to next prompt<br />
|-<br />
| GET || <code>/api/characters/{id}/audit_trail/</code> || View turn-by-turn audit history<br />
|-<br />
| GET || <code>/api/characters/{id}/game-state-changes/</code> || Timeline of state changes between turns<br />
|}<br />
<br />
==== Nested Character Resources ====<br />
<br />
For each character, full CRUD is available on:<br />
<br />
* <code>/api/characters/{id}/memories/</code> (plus <code>move_to_diary</code> and <code>restore_lost_memory</code> actions)<br />
* <code>/api/characters/{id}/experiences/</code><br />
* <code>/api/characters/{id}/skills/</code><br />
* <code>/api/characters/{id}/resources/</code><br />
* <code>/api/characters/{id}/marks/</code><br />
* <code>/api/characters/{id}/characters/</code> (known NPCs)<br />
* <code>/api/characters/{id}/pending-changes/</code><br />
<br />
==== Prompts ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Method !! Endpoint !! Description<br />
|-<br />
| GET || <code>/api/prompts/</code> || List all game prompts<br />
|-<br />
| GET || <code>/api/prompts/{prompt_id}/</code> || Retrieve a single prompt by ID<br />
|}<br />
<br />
=== Permissions and Security ===<br />
<br />
* All character data is scoped to the authenticated user via <code>IsCharacterOwner</code> permission.<br />
* JWT tokens are sent as <code>Authorization: Bearer {token}</code> headers.<br />
* The login endpoint is throttled (5/minute) to prevent brute-force attacks.<br />
* All pending changes are processed inside a database '''transaction''' to guarantee atomicity.<br />
* CORS headers are configured via <code>django-cors-headers</code>.<br />
<br />
== Frontend ==<br />
<br />
=== Views (Pages) ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! View !! Route !! Description<br />
|-<br />
| '''LoginView''' || <code>/login</code> || Authentication form; redirects authenticated users to home<br />
|-<br />
| '''HomeView''' || <code>/</code> || Dashboard showing all active characters in a card grid<br />
|-<br />
| '''CharacterCreationView''' || <code>/character-creation/:id</code> || Six-step creation wizard<br />
|-<br />
| '''GameView''' || <code>/game/:characterId</code> || Main game loop: prompt display, experience form, dice rolling, entity management, memory display<br />
|-<br />
| '''GameEndedView''' || <code>/game/:characterId/ended</code> || End-of-story screen with statistics and epilogue<br />
|-<br />
| '''RecordsView''' || <code>/records</code> || Archive of current and completed characters<br />
|-<br />
| '''StoryView''' || <code>/story/:characterId</code> || Narrative timeline with experience history, character stats sidebar, and epilogue<br />
|}<br />
<br />
All routes except <code>/login</code> require authentication. The router guard redirects unauthenticated users.<br />
<br />
=== Key Components ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Component !! Purpose<br />
|-<br />
| '''PromptSection''' || Displays the current prompt text, special rules, and dice roll results<br />
|-<br />
| '''ExperienceForm''' || Form for writing new experiences with title, date, content, and memory selection<br />
|-<br />
| '''MemoriesDisplay''' || Shows active, diary, and lost memories with experience counts; includes move-to-diary, delete, and restore actions<br />
|-<br />
| '''GameDataSection''' || Reusable list for skills, resources, or marks with add/edit/delete controls<br />
|-<br />
| '''CharactersSection''' || Grid of known NPCs with type badges and edit/delete<br />
|-<br />
| '''EntityCreationWindow''' || Draggable modal for creating/editing skills, resources, marks<br />
|-<br />
| '''CharacterCreationWindow''' || Draggable modal for creating/editing NPC characters<br />
|-<br />
| '''ExperienceEditWindow''' || Window for editing existing experience text<br />
|-<br />
| '''DiaryCreationModal''' || Modal for creating a diary resource and moving a memory into it<br />
|-<br />
| '''ConfirmationDialog''' || Generic confirmation dialog for destructive actions<br />
|-<br />
| '''ValidationWarning''' || Displays validation errors when game rules are not satisfied<br />
|}<br />
<br />
=== State Management (Pinia) ===<br />
<br />
Four Pinia stores manage application state:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Store !! Responsibility<br />
|-<br />
| '''auth''' || JWT token, user object, login/logout, token expiry handling<br />
|-<br />
| '''game''' || Characters list, current character, game state, all CRUD actions for entities, dice rolling, story continuation<br />
|-<br />
| '''characterCreation''' || Multi-step wizard data, initial character creation<br />
|-<br />
| '''theme''' || Dark/light mode toggle with localStorage persistence<br />
|}<br />
<br />
=== API Service Layer ===<br />
<br />
* '''<code>api.ts</code>''' – Axios instance with base URL auto-detection (development vs. production), request interceptor for JWT headers, response interceptor for 401/token-expiry handling.<br />
* '''<code>gameService.ts</code>''' – All API call methods: authentication, character CRUD, dice rolling, story continuation, memory/experience/skill/resource/mark/character management.<br />
* '''<code>entityService.ts</code>''' – Generic <code>EntityService</code> class instantiated for skills, resources, marks, and characters for DRY CRUD operations.<br />
<br />
=== Composables ===<br />
<br />
Vue composables encapsulate reusable business logic:<br />
<br />
* '''<code>useGameData()</code>''' – Computed properties derived from the game store (current character, memories, skills, resources, etc.)<br />
* '''<code>useExperienceForm()</code>''' – Form state, validation, memory selection, and reset logic<br />
* '''<code>useEntityManagement()</code>''' – Generic CRUD operations with optional confirmation dialogs<br />
* '''<code>useSkillManagement()</code>''', '''<code>useResourceManagement()</code>''', '''<code>useMarkManagement()</code>''', '''<code>useMemoryManagement()</code>''' – Specialised wrappers<br />
* '''<code>useConfirmationDialog()</code>''' – Promise-based modal confirmation<br />
* '''<code>useMemoryDisplay()</code>''' – Display logic for memories including pending-change awareness<br />
* '''<code>useExperienceDisplay()</code>''' – Markdown rendering for experience content<br />
* '''<code>usePendingChangesDisplay()</code>''' – Badge rendering for undo-able pending changes<br />
<br />
== Audit Trail ==<br />
<br />
The application includes an automatic audit trail that captures the complete game state every time the player advances to a new prompt.<br />
<br />
Each '''GameStateSnapshot''' records:<br />
<br />
* The turn number (sequential from 1)<br />
* The prompt transition (e.g. 36a → 34a)<br />
* The dice roll<br />
* A complete JSON snapshot of all memories, skills, resources, marks, and known characters<br />
* All pending changes that were committed<br />
<br />
The audit trail is accessible via:<br />
<br />
* '''API''': <code>GET /api/characters/{id}/audit_trail/</code> with optional <code>?turn=N</code> and <code>?limit=N</code> parameters<br />
* '''Management command''': <code>python manage.py view_audit_trail {id} [--summary] [--turn N] [--export file.json]</code><br />
* '''Timeline API''': <code>GET /api/characters/{id}/game-state-changes/</code> for a structured timeline of all state changes<br />
<br />
== Deployment ==<br />
<br />
=== Local Development ===<br />
<br />
<pre><br />
.\startup.ps1<br />
</pre><br />
<br />
This script creates a virtual environment, installs dependencies, runs migrations, and starts both the Django backend (<code>http://localhost:8000</code>) and the Vue dev server (<code>http://localhost:5173</code>).<br />
<br />
=== Production ===<br />
<br />
* Set <code>DJANGO_ENV=production</code><br />
* Build the frontend: <code>cd frontend && npm run build</code><br />
* Serve with Gunicorn behind a reverse proxy<br />
* Static files are collected into the <code>static/</code> directory<br />
* The production frontend points to <code>https://tyov.yusupov.cloud</code><br />
<br />
== Example: A Finished Character ==<br />
<br />
The following is an example of a character from an actual playthrough stored in the application database. It demonstrates how the game's mechanics play out over an extended narrative.<br />
<br />
=== Karmiš (formerly Ekurzu / Naram) ===<br />
<br />
'''Description:''' Naram was a temple scribe in the ancient city of Mari: meticulous, observant, and deeply entangled in the political and spiritual life of the city. His life was shaped by clay tablets, omens, and whispered secrets carried through palace corridors and temple courtyards. Behind his calm demeanor lies a mind constantly at work—recording, interpreting, and surviving.<br />
<br />
'''Prompts visited:''' 34 prompts across variations, including: 1a, 4a, 11a–c, 12a, 17a, 20a, 24a, 25a, 32a–b, 34a–36a, 37a–41c, 43a–c, 47a, 52a, 57a, 64a, 66a, 68a, 71a, 73a.<br />
<br />
'''Final prompt:''' 73a<br />
<br />
'''Memory slots lost:''' 1 · '''Memory slots gained:''' 1 (net effect: standard 5-memory limit)<br />
<br />
==== Epilogue ====<br />
<br />
<blockquote><br />
He has not died. Let me say that plainly. There will be no grave, no crumbling tomb, no name worn smooth by time. He is alive—quietly, deliberately, and utterly outside your reach.<br />
<br />
This book is not a memorial. It is a reckoning.<br />
<br />
When I first met him, I did not understand what he was. He wore his years like dust on old vellum—thin, barely visible, but ever present. [...] Over time, I became his mirror, then his partner, and—finally—his historian.<br />
<br />
But someone has to begin the telling. Someone has to place the first stone. So this book begins in a house of quiet gardens and low ceilings, where he writes in the mornings and feeds only when he must. [...]<br />
<br />
Just a man who remembered too much, for too long. And chose, in the end, ''peace''.<br />
<br />
— ''Mirelde''<br />
</blockquote><br />
<br />
==== Statistics ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Metric !! Count<br />
|-<br />
| Total memories || 16<br />
|-<br />
| Active memories || 5<br />
|-<br />
| Diary memories || 3<br />
|-<br />
| Lost (forgotten) memories || 8<br />
|-<br />
| Total experiences || 37<br />
|-<br />
| Skills || 11 (3 lost during play)<br />
|-<br />
| Resources || 10 (6 lost during play)<br />
|-<br />
| Marks || 2<br />
|-<br />
| Known characters || 11 (6 lost during play)<br />
|}<br />
<br />
==== Active Memories (at end of game) ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Memory Title !! Location !! Experiences<br />
|-<br />
| Memory 1 || Active || "Mortal life" (Initial), "The Name Given in Ash" (24a)<br />
|-<br />
| The Thorn and the Quill || Active || 1 experience (35a)<br />
|-<br />
| The Light That Does Not Burn || Active || "The Dawn at Mirelde's Fire" (52a), "The Dust in the Foundation" (57a)<br />
|-<br />
| We Were Not Counted Among the Cargo || Active || "The Bellies of Ships and Men" (64a), "Ink Without Meaning" (66a)<br />
|-<br />
| Echoes Before the Self Was Named || Active || "The Weight in the Smoke" (71a), "The Clay That Knew My Name" (68a)<br />
|}<br />
<br />
==== Diary Memories ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Memory Title !! Experiences<br />
|-<br />
| The Hill That Waits || "The Hollow Beneath the Cairn" (40a), "The Ring Beneath the Clay" (43c), "The Face Returned Through Time" (44a)<br />
|-<br />
| Ash of the Ledger || "The Last Ledger Vanishes" (38a), "The Fog Beneath Names" (39b), "The Weight of Unspoken Words" (34a)<br />
|-<br />
| The Fever-Ledger || "The Illness in Karkheda" (36a), "The Name That Returns in Ash" (41c), "The Echo That Cannot Translate" (47a)<br />
|}<br />
<br />
==== Lost Memories ====<br />
<br />
Eight memories were forgotten over the course of the game, including "The Forged Omen" (Memory 2), "Hessa's Last Message" (Memory 3), "Duel of Stars and Signs" (Memory 4), "The Turning", "The Name That Cannot Burn", "The Blood Between Accusations", "Trade Beneath Empire", and "What Was Meant to Last". These losses illustrate the game's core mechanic: as new experiences accumulate, the vampire is forced to sacrifice older memories, creating a poignant sense of identity erosion across the centuries.<br />
<br />
==== Skills ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Skill !! Status !! Description (excerpt)<br />
|-<br />
| Ash-Tongue || {{Checked}} || "I speak in soot and suggestion, in the cracks between laws."<br />
|-<br />
| Bloodthirsty || {{Lost}} || "The scent of mortal blood calls to me like a hymn in the dark."<br />
|-<br />
| Ceremonial Composure || {{Checked}} || "In the presence of gods or kings, my face is unreadable."<br />
|-<br />
| Decipher Ancient Texts || {{Lost}} || "I can read languages long dead and spot forgeries."<br />
|-<br />
| I Control the Beast || {{Lost}} || "When the thirst rises, I do not flinch. I meet the monster's gaze."<br />
|-<br />
| Ledger Without End || Normal || "Born from the quiet rituals of inventory and account."<br />
|-<br />
| Physick of the Pale Vein || Normal || "I feed gently, beneath the guise of care."<br />
|-<br />
| Remain in Unknowing || {{Checked}} || "I do not flee the edges of memory."<br />
|-<br />
| Silent Cartography || {{Checked}} || "I trace the unseen paths between people, places, and power."<br />
|-<br />
| Snare and Stillness || {{Checked}} || "I move with silence that makes mortals forget they heard me."<br />
|-<br />
| Tongue of the Unnamed || Normal || "I no longer understand the languages of my past, but I wear the sounds of others like masks."<br />
|}<br />
<br />
==== Resources ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Resource !! Type !! Status !! Notes<br />
|-<br />
| Kept Against Forgetting || Portable / '''Diary''' || Active || The character's diary; written with Mirelde<br />
|-<br />
| Tablet Bearing My Name || Portable || Active || A clay tablet from the ancient past, rediscovered<br />
|-<br />
| The Margins of Manifest || Portable || Active || A cipher-folio cataloguing names of the enslaved<br />
|-<br />
| Burrowed Sanctum || Portable || Lost || An earthen chamber beneath a forgotten altar<br />
|-<br />
| Chamber of Whispers || Stationary || Lost || A hidden storeroom beneath the temple of Ishtar<br />
|-<br />
| Clay Tablets and Reed Stylus || Portable || Lost || Writing implements used by instinct, not understanding<br />
|-<br />
| Hidden Archive Tablet || Portable || Lost || A tablet inscribed with dynasty-breaking truths<br />
|-<br />
| The Monastery Diary || Portable / Diary || Lost || A former diary, lost when the monastery fell<br />
|-<br />
| The Silent Authority || Portable || Lost || A carved seal whose symbols can no longer be read<br />
|-<br />
| The Walls of Forgetting || Stationary / Diary || Lost || Memory carvings in five scripts beneath a forgotten shrine<br />
|}<br />
<br />
==== Known Characters ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Name !! Type !! Relationship !! Status<br />
|-<br />
| Ashurban the Veiled || Immortal || Neutral || Active<br />
|-<br />
| Mirelde of Bracha || Immortal || Friend || Active<br />
|-<br />
| The One Who Does Not Answer || Mortal || Neutral || Active<br />
|-<br />
| Thoöni (spectral) || Immortal || Neutral || Active<br />
|-<br />
| Belatu || Mortal || Rival || Lost<br />
|-<br />
| Ennatum || Mortal || Friend || Lost<br />
|-<br />
| Hessa || Mortal || Love || Lost<br />
|-<br />
| Ibbi-Zamri || Mortal || Mentor || Lost<br />
|-<br />
| Mekha || Mortal || Enemy || Lost<br />
|-<br />
| Pelagon || Mortal || Enemy || Lost<br />
|-<br />
| Thoöni (scholar) || Mortal || Friend || Lost<br />
|}<br />
<br />
==== Marks ====<br />
<br />
{| class="wikitable"<br />
|-<br />
! Mark !! Description<br />
|-<br />
| The Unblinking Eye || An ancient eye-like scar below the collarbone; burns faintly in the presence of lies<br />
|-<br />
| The Gesture Forbidden || An involuntary three-fingered gesture of silence, often mistaken for mockery<br />
|}<br />
<br />
==== Example Experience: "The Bellies of Ships and Men" (Prompt 64a) ====<br />
<br />
<blockquote><br />
They arrived in numbers too vast to count—pressed between barrels, chained to holds slick with piss and seawater, branded, sick, broken. And the sailors were not much better.<br />
<br />
The ships would come in [...]<br />
</blockquote><br />
<br />
''Date: around 1510 CE''<br />
<br />
This experience is part of the memory "We Were Not Counted Among the Cargo", illustrating the vampire's witness to the Atlantic slave trade—one of many historical eras the character passes through during a millennium-spanning story.<br />
<br />
== Testing ==<br />
<br />
=== Backend ===<br />
<br />
Tests are run with '''pytest''' and '''pytest-django''':<br />
<br />
<pre><br />
pytest<br />
</pre><br />
<br />
Test files include:<br />
* <code>vampire/test_models.py</code> – model unit tests<br />
* <code>tyov_api/test_api.py</code> – API endpoint integration tests<br />
* <code>tyov_api/test_models.py</code> – API model tests<br />
* <code>authentication/test_views.py</code> – authentication tests<br />
<br />
=== Frontend ===<br />
<br />
End-to-end tests use '''Playwright''':<br />
<br />
<pre><br />
cd frontend<br />
npx playwright test<br />
</pre><br />
<br />
Test specs include:<br />
* <code>e2e/character-creation-workflow.spec.ts</code> – character creation wizard<br />
* <code>e2e/tyov-game.spec.ts</code> – game loop testing<br />
* <code>e2e/vue.spec.ts</code> – general Vue component tests<br />
<br />
== See Also ==<br />
<br />
* ''Thousand Year Old Vampire'' by Tim Hutchings – the original tabletop game<br />
* [[Django (web framework)]]<br />
* [[Vue.js]]<br />
* [[Single-page application]]<br />
<br />
== References ==<br />
<br />
{{Reflist}}<br />
<br />
[[Category:Web applications]]<br />
[[Category:Role-playing video games]]<br />
[[Category:Django (web framework) applications]]<br />
[[Category:Vue.js applications]]<br />
[[Category:Solo role-playing games]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Yusupov.cloud&diff=383Yusupov.cloud2026-04-12T11:15:28Z<p>Mvuijlst: /* Subdomains and projects */</p>
<hr />
<div>{{Infobox<br />
| name = yusupov.cloud<br />
| 1 url = https://yusupov.cloud<br />
| 2 type = Personal web sites<br />
| 3 owner = [[Michel Vuijlsteke]]<br />
| 4 launched = 2025<br />
| 5 current_status = Online<br />
}}<br />
<br />
'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref><br />
<br />
== Overview ==<br />
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref><br />
<br />
== Subdomains and projects ==<br />
Publicly visible projects include:<br />
<br />
* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref><br />
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref><br />
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — ''Cloud'', a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref><br />
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''Digest'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref><br />
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref><br />
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''Quidlibet'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref><br />
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''[[Thousand Year Old Vampire]]'', with Django 5 backend and Vue 3 frontend. (Per operator.)<br />
<br />
Operator-reported (not publicly discoverable at time of writing):<br />
<br />
* skills.yusupov.cloud — a skills matrix application. (Per operator.)<br />
* resources.yusupov.cloud — a simple resource plannign calendar. (Per operator.)<br />
<br />
== Technology ==<br />
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" /><br />
<br />
== Relation to the BBS ==<br />
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref><br />
<br />
== See also ==<br />
* [[Yusupov's House]] (1990s BBS)<br />
* [[Michel Vuijlsteke]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Personal websites]]<br />
[[Category:Belgian websites]]<br />
[[Category:2025 establishments in Belgium]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Echoes_of_What_Wasn%27t&diff=382Echoes of What Wasn't2026-04-12T11:03:05Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| 01_name = Echoes of What Wasn't<br />
| 02_url = https://echoes.yusupov.cloud<br />
| 03_developer = Michel Vuijlsteke<br />
| 04_released = 2025<br />
| 05_genre = AI-generated alternate-history newspaper<br />
| 06_language = Python<br />
| 07_framework = [[Django]] 5.2 / [[Wagtail]] 7.3<br />
| 08_license = Proprietary<br />
}}<br />
<br />
'''Echoes of What Wasn't''' (also known as '''Echoes''') is a web application hosted at <code>echoes.yusupov.cloud</code> that publishes AI-generated alternate-history newspaper and magazine articles. Each article takes a real historical event, invents a plausible point of divergence, and presents the consequences as an in-world retrospective written decades later by a fictitious journalist for a fictitious period-appropriate publication. The site's tagline is "Dispatches from Histories That Never Were."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Django 5.2 with Wagtail 7.3 as its content management system.<ref name="requirements">requirements.txt in the project repository lists Django 5.2.12 and Wagtail 7.3.1.</ref> It uses [[Django REST framework]] for a JSON API, [[SQLite]] as its database, and is deployed behind [[Nginx]] with [[Gunicorn]] on a Linux server. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing, [[nh3 (library)|nh3]] for HTML sanitisation, [[Beautiful Soup (HTML parser)|Beautiful Soup]] and [[lxml]] for scraping, and the [[OpenAI]] Python client for language-model and image-generation calls. Geographic features use <code>wagtailgeowidget</code> with Google Maps integration.<br />
<br />
== Data model ==<br />
<br />
=== Article pages ===<br />
<br />
Each article is a Wagtail <code>ArticlePage</code>, a child of a single <code>ArticleIndexPage</code> in the page tree. An article carries:<br />
<br />
* ''title'', ''subtitle'', ''publication'' (the fictitious newspaper/magazine name), ''date'' (in-universe publication date), ''event_date'' (the historical event's date), ''location'', and a foreign key to an <code>Author</code> snippet (exposed via the API as ''byline'').<br />
* A ''body_richtext'' field (Wagtail <code>RichTextField</code>) containing the article's HTML body, sanitised on ingest.<br />
* A ''body'' [[Wagtail StreamField|StreamField]] supporting paragraph, heading, callout, quote, pull-quote, bulleted list, numbered list, image, aside (with its own nested stream), and horizontal-rule block types.<br />
* Separate ''callouts'' and ''quotes'' StreamFields for editorial pull-outs and attributed quotations.<br />
* A JSON ''assets'' field listing image metadata (src, alt, caption, credit, prompt).<br />
* A ''featured_image'' foreign key to a custom image model (<code>CustomImage</code>, extending Wagtail's <code>AbstractImage</code> with a description field).<br />
* Internal editorial fields: ''original_event'', ''departure_point'', and ''ai_context'', which are visible in the Wagtail admin but not rendered on the public site.<br />
* Geographic fields: ''event_location'' (address string), ''geo_location'' (WKT point), ''latitude'', and ''longitude''. The model's <code>save()</code> method synchronises the WKT point and decimal-degree fields bidirectionally.<br />
<br />
=== Historical events ===<br />
<br />
The <code>HistoricalEvent</code> model stores real events scraped from Wikipedia, keyed by ISO date, astronomical year, event text, language code, and a boolean ''used'' flag.<br />
<br />
=== Custom images ===<br />
<br />
<code>CustomImage</code> and <code>CustomRendition</code> extend Wagtail's abstract image models to add a ''description'' text field, used to store the original DALL·E prompt.<br />
<br />
== Article generation pipeline ==<br />
<br />
Article generation is performed by the standalone script <code>_generate_article.py</code>, which orchestrates a six-step pipeline of OpenAI API calls, checkpoint-resumed so that a failure at any step does not waste prior work. The default text model is GPT-5 (with GPT-4o as fallback); the image model is <code>gpt-image-1</code>.<br />
<br />
=== Step 0: Event sourcing ===<br />
<br />
A separate scraper (<code>_scrape_wikipedia_events.py</code>) fetches every day-of-year page from Wikipedia (e.g. "January 1", "February 14") for English, French, and Dutch editions. It parses the "Events" sections, extracts each entry's year and text, and stores them as <code>HistoricalEvent</code> rows. The scraper respects rate limits and identifies itself via a custom User-Agent string.<br />
<br />
=== Step 1: Event selection ===<br />
<br />
The pipeline queries the database for unused Common Era events whose month and day match the current date and whose year is at least 50 years in the past. Five candidates are sampled at random and presented in a structured prompt to the text model, which acts as an "editorial planner." The model returns JSON selecting the single most promising event for an alternate-history feature, together with a proposed divergence date, publication date, publication context (name, type, city, editorial stance, intended readership), article angle, and a list of visual possibilities. The pipeline validates that the chosen event ID was in the candidate set.<br />
<br />
=== Step 2: Timeline brief ===<br />
<br />
The selection JSON is fed into a second prompt that asks the model to build an "internal dossier" — a compact alternate-history world brief. This includes:<br />
<br />
* A core timeline premise.<br />
* A chronological ''historical_path'' of at least five entries spanning from divergence to publication date.<br />
* Canonical facts to preserve (real-world events outside the divergence's causal chain).<br />
* "Real-history traps to avoid" — events whose preconditions are disrupted by the divergence.<br />
* In-world assumptions (what ordinary readers take for granted).<br />
* Named entities (people, institutions, treaties, technologies) specific to this timeline.<br />
* An article brief (genre, tone, writer persona, central question, thesis, section ideas).<br />
* Style constraints (bans on meta-framing, "not X but Y" constructions, poetic codas, excessive em-dashes and exclamation marks).<br />
* A visual brief for the photo editor.<br />
<br />
This step enforces a "proportional divergence rule": the timeline should change only what the divergence actually changes, and leave causally unrelated real-world events intact.<br />
<br />
=== Step 3: Article generation ===<br />
<br />
The selection and timeline-brief JSONs are combined in a third prompt which instructs the model to write the full article as a single JSON object. The article must:<br />
<br />
* Be written entirely from inside the alternate timeline, with no meta-framing or comparison to real history.<br />
* Be at least 1,500 words across its <code>body_blocks</code>.<br />
* Include at least two callout blocks and one attributed quote block, interleaved naturally.<br />
* Use period-appropriate prose matching the in-world date, place, and publication culture.<br />
* Be entirely in the language of the source event (English, French, or Dutch).<br />
* Include a hero-image prompt (in English) and geographic coordinates.<br />
<br />
The model is asked to self-check for in-world consistency, language correctness, and structural validity before outputting. If the returned JSON is malformed, a repair prompt asks the model to fix it.<br />
<br />
=== Step 4: In-world edit ===<br />
<br />
The draft JSON is passed through a fourth "line editor" prompt. This step:<br />
<br />
* Preserves meaning, canon, and timeline integrity.<br />
* Removes AI-flavored rhetoric ("not X, but Y" constructions, pseudo-poetic endings, inflated abstraction, repetitive thesis phrasing).<br />
* Replaces any accidental references to real-world events that should not exist in the diverged timeline.<br />
* Forces the canonical event and publication dates from the selection step.<br />
* Populates the internal ''original_event'', ''departure_point'', and ''ai_context'' fields.<br />
<br />
The pipeline then validates the edited payload: checking required fields, enforcing the ban on meta-themed publication names, verifying date consistency with the selection, confirming minimum callout and quote counts, and ensuring no quote is attributed to the article's own author.<br />
<br />
=== Step 5: Image prompts ===<br />
<br />
A fifth prompt, addressed to a "photo editor and visual archivist," generates one to five image concepts. Each concept specifies:<br />
<br />
* A role (hero or supporting).<br />
* An aspect ratio (landscape, portrait, or square).<br />
* A detailed English-language image prompt.<br />
* Alt text, caption, and credit in the article language.<br />
<br />
The prompt includes extensive rules for period-appropriate visual media (daguerreotype for 1840–1880, silver gelatin for 1880–1930, Kodachrome for 1970–2000, and so on), and bans on text in images, symmetrical compositions, "dramatic lighting," and modern digital-art aesthetics. The returned concepts are normalised: roles are deduplicated, aspect ratios are validated, and the set is capped at five images.<br />
<br />
=== Step 6: Image generation and upload ===<br />
<br />
Each image prompt is wrapped in additional instructions enforcing candid documentary realism (or authentic non-photographic media for paintings, engravings, and archival objects) before being sent to OpenAI's image-generation endpoint (<code>gpt-image-1</code>). Generated images are decoded from base64, converted to optimised progressive JPEG via Pillow, and uploaded through the application's <code>/api/media</code> endpoint. The hero image is set as the article's ''featured_image''. Non-hero images are inserted into the <code>body_blocks</code> array at evenly spaced positions.<br />
<br />
=== Step 7: Publication ===<br />
<br />
The assembled JSON payload — with body blocks, assets, featured image, byline, callouts, quotes, and editorial metadata — is POSTed to the <code>/api/articles</code> endpoint. The API serializer sanitises body HTML via nh3, resolves image file paths to Wagtail embed tags, creates or looks up the <code>Author</code> snippet, attaches the article as a child of the <code>ArticleIndexPage</code>, and publishes it. The source <code>HistoricalEvent</code> is marked as used. The checkpoint file is cleared.<br />
<br />
== REST API ==<br />
<br />
The application exposes a JSON API under <code>/api/</code>, protected by bearer-token authentication for write operations and publicly readable:<br />
<br />
* <code>GET/POST /api/articles</code> — list (paginated) or create articles.<br />
* <code>GET/PUT /api/articles/<id></code> — retrieve or update a single article.<br />
* <code>POST /api/media</code> — upload a base64-encoded image, which is stored as a <code>CustomImage</code>.<br />
* <code>GET /api/markers</code> — return geographic markers for all geolocated articles.<br />
* <code>GET /api/schema</code> — serve the OpenAPI specification.<br />
<br />
Public documentation is available at <code>/docs</code> (ReDoc) and <code>/swagger</code> (Swagger UI).<br />
<br />
== Public interface ==<br />
<br />
=== Home page ===<br />
<br />
The <code>ArticleIndexPage</code> serves as the site's home page, displaying up to seven recent articles, a "picture desk" mosaic of up to fifteen images (sampled hourly for variety), a map teaser with up to four geolocated articles, and navigation links for monthly archives.<br />
<br />
=== Article pages ===<br />
<br />
Each article page features a full-bleed hero image (when available), a masthead with the fictitious publication name, headline, subtitle, byline, dateline, and the event date. The body renders the StreamField blocks: paragraphs, headings, images with captions and credits, callouts, attributed quotes, pull quotes, bulleted and numbered lists, asides with nested content, and horizontal rules.<br />
<br />
=== Where/When ===<br />
<br />
An interactive "Where & When" page presents all geolocated articles on a [[Leaflet (software)|Leaflet]] map (using CartoDB tiles with light/dark themes) alongside a zoomable timeline. Articles are plotted by their event location and date. The map and article data are loaded via the <code>/api/markers</code> endpoint.<br />
<br />
=== Monthly archives ===<br />
<br />
Articles can be browsed by the month of their in-universe event date. The index page dynamically builds archive links with article counts per month.<br />
<br />
=== Theme ===<br />
<br />
The site supports light and dark colour themes, toggled via a button in the masthead and persisted in <code>localStorage</code>. Typography uses Playfair Display for display headings, Source Serif 4 for body text, and Inter for UI elements.<br />
<br />
== Multilingual support ==<br />
<br />
The Wikipedia scraper and article-generation pipeline support English, French, and Dutch. The language of each historical event is stored in the database and carried through to the generation prompts, which instruct the model to write all visible article content — title, subtitle, body, captions, quotes, and credits — in the source event's language. Internal editorial fields and image prompts remain in English.<br />
<br />
== See also ==<br />
<br />
* [[Alternate history]]<br />
* [[Wagtail (CMS)]]<br />
* [[OpenAI]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Echoes_of_What_Wasn%27t&diff=381Echoes of What Wasn't2026-04-12T11:02:03Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| name = Echoes of What Wasn't<br />
| url = {{URL|https://echoes.yusupov.cloud}}<br />
| developer = Operator<br />
| released = 2025<br />
| genre = AI-generated alternate-history newspaper<br />
| language = Python<br />
| framework = [[Django]] 5.2 / [[Wagtail]] 7.3<br />
| license = Proprietary<br />
}}<br />
<br />
'''Echoes of What Wasn't''' (also known as '''Echoes''') is a web application hosted at <code>echoes.yusupov.cloud</code> that publishes AI-generated alternate-history newspaper and magazine articles. Each article takes a real historical event, invents a plausible point of divergence, and presents the consequences as an in-world retrospective written decades later by a fictitious journalist for a fictitious period-appropriate publication. The site's tagline is "Dispatches from Histories That Never Were."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Django 5.2 with Wagtail 7.3 as its content management system.<ref name="requirements">requirements.txt in the project repository lists Django 5.2.12 and Wagtail 7.3.1.</ref> It uses [[Django REST framework]] for a JSON API, [[SQLite]] as its database, and is deployed behind [[Nginx]] with [[Gunicorn]] on a Linux server. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing, [[nh3 (library)|nh3]] for HTML sanitisation, [[Beautiful Soup (HTML parser)|Beautiful Soup]] and [[lxml]] for scraping, and the [[OpenAI]] Python client for language-model and image-generation calls. Geographic features use <code>wagtailgeowidget</code> with Google Maps integration.<br />
<br />
== Data model ==<br />
<br />
=== Article pages ===<br />
<br />
Each article is a Wagtail <code>ArticlePage</code>, a child of a single <code>ArticleIndexPage</code> in the page tree. An article carries:<br />
<br />
* ''title'', ''subtitle'', ''publication'' (the fictitious newspaper/magazine name), ''date'' (in-universe publication date), ''event_date'' (the historical event's date), ''location'', and a foreign key to an <code>Author</code> snippet (exposed via the API as ''byline'').<br />
* A ''body_richtext'' field (Wagtail <code>RichTextField</code>) containing the article's HTML body, sanitised on ingest.<br />
* A ''body'' [[Wagtail StreamField|StreamField]] supporting paragraph, heading, callout, quote, pull-quote, bulleted list, numbered list, image, aside (with its own nested stream), and horizontal-rule block types.<br />
* Separate ''callouts'' and ''quotes'' StreamFields for editorial pull-outs and attributed quotations.<br />
* A JSON ''assets'' field listing image metadata (src, alt, caption, credit, prompt).<br />
* A ''featured_image'' foreign key to a custom image model (<code>CustomImage</code>, extending Wagtail's <code>AbstractImage</code> with a description field).<br />
* Internal editorial fields: ''original_event'', ''departure_point'', and ''ai_context'', which are visible in the Wagtail admin but not rendered on the public site.<br />
* Geographic fields: ''event_location'' (address string), ''geo_location'' (WKT point), ''latitude'', and ''longitude''. The model's <code>save()</code> method synchronises the WKT point and decimal-degree fields bidirectionally.<br />
<br />
=== Historical events ===<br />
<br />
The <code>HistoricalEvent</code> model stores real events scraped from Wikipedia, keyed by ISO date, astronomical year, event text, language code, and a boolean ''used'' flag.<br />
<br />
=== Custom images ===<br />
<br />
<code>CustomImage</code> and <code>CustomRendition</code> extend Wagtail's abstract image models to add a ''description'' text field, used to store the original DALL·E prompt.<br />
<br />
== Article generation pipeline ==<br />
<br />
Article generation is performed by the standalone script <code>_generate_article.py</code>, which orchestrates a six-step pipeline of OpenAI API calls, checkpoint-resumed so that a failure at any step does not waste prior work. The default text model is GPT-5 (with GPT-4o as fallback); the image model is <code>gpt-image-1</code>.<br />
<br />
=== Step 0: Event sourcing ===<br />
<br />
A separate scraper (<code>_scrape_wikipedia_events.py</code>) fetches every day-of-year page from Wikipedia (e.g. "January 1", "February 14") for English, French, and Dutch editions. It parses the "Events" sections, extracts each entry's year and text, and stores them as <code>HistoricalEvent</code> rows. The scraper respects rate limits and identifies itself via a custom User-Agent string.<br />
<br />
=== Step 1: Event selection ===<br />
<br />
The pipeline queries the database for unused Common Era events whose month and day match the current date and whose year is at least 50 years in the past. Five candidates are sampled at random and presented in a structured prompt to the text model, which acts as an "editorial planner." The model returns JSON selecting the single most promising event for an alternate-history feature, together with a proposed divergence date, publication date, publication context (name, type, city, editorial stance, intended readership), article angle, and a list of visual possibilities. The pipeline validates that the chosen event ID was in the candidate set.<br />
<br />
=== Step 2: Timeline brief ===<br />
<br />
The selection JSON is fed into a second prompt that asks the model to build an "internal dossier" — a compact alternate-history world brief. This includes:<br />
<br />
* A core timeline premise.<br />
* A chronological ''historical_path'' of at least five entries spanning from divergence to publication date.<br />
* Canonical facts to preserve (real-world events outside the divergence's causal chain).<br />
* "Real-history traps to avoid" — events whose preconditions are disrupted by the divergence.<br />
* In-world assumptions (what ordinary readers take for granted).<br />
* Named entities (people, institutions, treaties, technologies) specific to this timeline.<br />
* An article brief (genre, tone, writer persona, central question, thesis, section ideas).<br />
* Style constraints (bans on meta-framing, "not X but Y" constructions, poetic codas, excessive em-dashes and exclamation marks).<br />
* A visual brief for the photo editor.<br />
<br />
This step enforces a "proportional divergence rule": the timeline should change only what the divergence actually changes, and leave causally unrelated real-world events intact.<br />
<br />
=== Step 3: Article generation ===<br />
<br />
The selection and timeline-brief JSONs are combined in a third prompt which instructs the model to write the full article as a single JSON object. The article must:<br />
<br />
* Be written entirely from inside the alternate timeline, with no meta-framing or comparison to real history.<br />
* Be at least 1,500 words across its <code>body_blocks</code>.<br />
* Include at least two callout blocks and one attributed quote block, interleaved naturally.<br />
* Use period-appropriate prose matching the in-world date, place, and publication culture.<br />
* Be entirely in the language of the source event (English, French, or Dutch).<br />
* Include a hero-image prompt (in English) and geographic coordinates.<br />
<br />
The model is asked to self-check for in-world consistency, language correctness, and structural validity before outputting. If the returned JSON is malformed, a repair prompt asks the model to fix it.<br />
<br />
=== Step 4: In-world edit ===<br />
<br />
The draft JSON is passed through a fourth "line editor" prompt. This step:<br />
<br />
* Preserves meaning, canon, and timeline integrity.<br />
* Removes AI-flavored rhetoric ("not X, but Y" constructions, pseudo-poetic endings, inflated abstraction, repetitive thesis phrasing).<br />
* Replaces any accidental references to real-world events that should not exist in the diverged timeline.<br />
* Forces the canonical event and publication dates from the selection step.<br />
* Populates the internal ''original_event'', ''departure_point'', and ''ai_context'' fields.<br />
<br />
The pipeline then validates the edited payload: checking required fields, enforcing the ban on meta-themed publication names, verifying date consistency with the selection, confirming minimum callout and quote counts, and ensuring no quote is attributed to the article's own author.<br />
<br />
=== Step 5: Image prompts ===<br />
<br />
A fifth prompt, addressed to a "photo editor and visual archivist," generates one to five image concepts. Each concept specifies:<br />
<br />
* A role (hero or supporting).<br />
* An aspect ratio (landscape, portrait, or square).<br />
* A detailed English-language image prompt.<br />
* Alt text, caption, and credit in the article language.<br />
<br />
The prompt includes extensive rules for period-appropriate visual media (daguerreotype for 1840–1880, silver gelatin for 1880–1930, Kodachrome for 1970–2000, and so on), and bans on text in images, symmetrical compositions, "dramatic lighting," and modern digital-art aesthetics. The returned concepts are normalised: roles are deduplicated, aspect ratios are validated, and the set is capped at five images.<br />
<br />
=== Step 6: Image generation and upload ===<br />
<br />
Each image prompt is wrapped in additional instructions enforcing candid documentary realism (or authentic non-photographic media for paintings, engravings, and archival objects) before being sent to OpenAI's image-generation endpoint (<code>gpt-image-1</code>). Generated images are decoded from base64, converted to optimised progressive JPEG via Pillow, and uploaded through the application's <code>/api/media</code> endpoint. The hero image is set as the article's ''featured_image''. Non-hero images are inserted into the <code>body_blocks</code> array at evenly spaced positions.<br />
<br />
=== Step 7: Publication ===<br />
<br />
The assembled JSON payload — with body blocks, assets, featured image, byline, callouts, quotes, and editorial metadata — is POSTed to the <code>/api/articles</code> endpoint. The API serializer sanitises body HTML via nh3, resolves image file paths to Wagtail embed tags, creates or looks up the <code>Author</code> snippet, attaches the article as a child of the <code>ArticleIndexPage</code>, and publishes it. The source <code>HistoricalEvent</code> is marked as used. The checkpoint file is cleared.<br />
<br />
== REST API ==<br />
<br />
The application exposes a JSON API under <code>/api/</code>, protected by bearer-token authentication for write operations and publicly readable:<br />
<br />
* <code>GET/POST /api/articles</code> — list (paginated) or create articles.<br />
* <code>GET/PUT /api/articles/<id></code> — retrieve or update a single article.<br />
* <code>POST /api/media</code> — upload a base64-encoded image, which is stored as a <code>CustomImage</code>.<br />
* <code>GET /api/markers</code> — return geographic markers for all geolocated articles.<br />
* <code>GET /api/schema</code> — serve the OpenAPI specification.<br />
<br />
Public documentation is available at <code>/docs</code> (ReDoc) and <code>/swagger</code> (Swagger UI).<br />
<br />
== Public interface ==<br />
<br />
=== Home page ===<br />
<br />
The <code>ArticleIndexPage</code> serves as the site's home page, displaying up to seven recent articles, a "picture desk" mosaic of up to fifteen images (sampled hourly for variety), a map teaser with up to four geolocated articles, and navigation links for monthly archives.<br />
<br />
=== Article pages ===<br />
<br />
Each article page features a full-bleed hero image (when available), a masthead with the fictitious publication name, headline, subtitle, byline, dateline, and the event date. The body renders the StreamField blocks: paragraphs, headings, images with captions and credits, callouts, attributed quotes, pull quotes, bulleted and numbered lists, asides with nested content, and horizontal rules.<br />
<br />
=== Where/When ===<br />
<br />
An interactive "Where & When" page presents all geolocated articles on a [[Leaflet (software)|Leaflet]] map (using CartoDB tiles with light/dark themes) alongside a zoomable timeline. Articles are plotted by their event location and date. The map and article data are loaded via the <code>/api/markers</code> endpoint.<br />
<br />
=== Monthly archives ===<br />
<br />
Articles can be browsed by the month of their in-universe event date. The index page dynamically builds archive links with article counts per month.<br />
<br />
=== Theme ===<br />
<br />
The site supports light and dark colour themes, toggled via a button in the masthead and persisted in <code>localStorage</code>. Typography uses Playfair Display for display headings, Source Serif 4 for body text, and Inter for UI elements.<br />
<br />
== Multilingual support ==<br />
<br />
The Wikipedia scraper and article-generation pipeline support English, French, and Dutch. The language of each historical event is stored in the database and carried through to the generation prompts, which instruct the model to write all visible article content — title, subtitle, body, captions, quotes, and credits — in the source event's language. Internal editorial fields and image prompts remain in English.<br />
<br />
== See also ==<br />
<br />
* [[Alternate history]]<br />
* [[Wagtail (CMS)]]<br />
* [[OpenAI]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Echoes_of_What_Wasn%27t&diff=380Echoes of What Wasn't2026-04-12T11:00:37Z<p>Mvuijlst: Created page with "{{Infobox software | name = Echoes of What Wasn't | url = {{URL|https://echoes.yusupov.cloud}} | developer = Operator | released = 2025 | genre = AI-generated alternate-history newspaper | language = Python | framework = Django 5.2 / Wagtail 7.3 | license = Proprietary }} '''Echoes of What Wasn't''' (also known as '''Echoes''') is a web application hosted at <code>echoes.yusupov.cloud</code> that publishes AI-generated..."</p>
<hr />
<div>{{Infobox software<br />
| name = Echoes of What Wasn't<br />
| url = {{URL|https://echoes.yusupov.cloud}}<br />
| developer = Operator<br />
| released = 2025<br />
| genre = AI-generated alternate-history newspaper<br />
| language = Python<br />
| framework = [[Django]] 5.2 / [[Wagtail]] 7.3<br />
| license = Proprietary<br />
}}<br />
<br />
'''Echoes of What Wasn't''' (also known as '''Echoes''') is a web application hosted at <code>echoes.yusupov.cloud</code> that publishes AI-generated alternate-history newspaper and magazine articles. Each article takes a real historical event, invents a plausible point of divergence, and presents the consequences as an in-world retrospective written decades later by a fictitious journalist for a fictitious period-appropriate publication. The site's tagline is "Dispatches from Histories That Never Were."<br />
<br />
== Technology stack ==<br />
<br />
The application is built on Django 5.2 with Wagtail 7.3 as its content management system.<ref name="requirements">requirements.txt in the project repository lists Django 5.2.12 and Wagtail 7.3.1.</ref> It uses [[Django REST framework]] for a JSON API, [[SQLite]] as its database, and is deployed behind [[Nginx]] with [[Gunicorn]] on a Linux server. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing, [[nh3 (library)|nh3]] for HTML sanitisation, [[Beautiful Soup (HTML parser)|Beautiful Soup]] and [[lxml]] for scraping, and the [[OpenAI]] Python client for language-model and image-generation calls. Geographic features use <code>wagtailgeowidget</code> with Google Maps integration.<br />
<br />
== Data model ==<br />
<br />
=== Article pages ===<br />
<br />
Each article is a Wagtail <code>ArticlePage</code>, a child of a single <code>ArticleIndexPage</code> in the page tree. An article carries:<br />
<br />
* ''title'', ''subtitle'', ''publication'' (the fictitious newspaper/magazine name), ''date'' (in-universe publication date), ''event_date'' (the historical event's date), ''location'', and a foreign key to an <code>Author</code> snippet (exposed via the API as ''byline'').<br />
* A ''body_richtext'' field (Wagtail <code>RichTextField</code>) containing the article's HTML body, sanitised on ingest.<br />
* A ''body'' [[Wagtail StreamField|StreamField]] supporting paragraph, heading, callout, quote, pull-quote, bulleted list, numbered list, image, aside (with its own nested stream), and horizontal-rule block types.<br />
* Separate ''callouts'' and ''quotes'' StreamFields for editorial pull-outs and attributed quotations.<br />
* A JSON ''assets'' field listing image metadata (src, alt, caption, credit, prompt).<br />
* A ''featured_image'' foreign key to a custom image model (<code>CustomImage</code>, extending Wagtail's <code>AbstractImage</code> with a description field).<br />
* Internal editorial fields: ''original_event'', ''departure_point'', and ''ai_context'', which are visible in the Wagtail admin but not rendered on the public site.<br />
* Geographic fields: ''event_location'' (address string), ''geo_location'' (WKT point), ''latitude'', and ''longitude''. The model's <code>save()</code> method synchronises the WKT point and decimal-degree fields bidirectionally.<br />
<br />
=== Historical events ===<br />
<br />
The <code>HistoricalEvent</code> model stores real events scraped from Wikipedia, keyed by ISO date, astronomical year, event text, language code, and a boolean ''used'' flag.<br />
<br />
=== Custom images ===<br />
<br />
<code>CustomImage</code> and <code>CustomRendition</code> extend Wagtail's abstract image models to add a ''description'' text field, used to store the original DALL·E prompt.<br />
<br />
== Article generation pipeline ==<br />
<br />
Article generation is performed by the standalone script <code>_generate_article.py</code>, which orchestrates a six-step pipeline of OpenAI API calls, checkpoint-resumed so that a failure at any step does not waste prior work. The default text model is GPT-5 (with GPT-4o as fallback); the image model is <code>gpt-image-1</code>.<br />
<br />
=== Step 0: Event sourcing ===<br />
<br />
A separate scraper (<code>_scrape_wikipedia_events.py</code>) fetches every day-of-year page from Wikipedia (e.g. "January 1", "February 14") for English, French, and Dutch editions. It parses the "Events" sections, extracts each entry's year and text, and stores them as <code>HistoricalEvent</code> rows. The scraper respects rate limits and identifies itself via a custom User-Agent string.<br />
<br />
=== Step 1: Event selection ===<br />
<br />
The pipeline queries the database for unused Common Era events whose month and day match the current date and whose year is at least 50 years in the past. Five candidates are sampled at random and presented in a structured prompt to the text model, which acts as an "editorial planner." The model returns JSON selecting the single most promising event for an alternate-history feature, together with a proposed divergence date, publication date, publication context (name, type, city, editorial stance, intended readership), article angle, and a list of visual possibilities. The pipeline validates that the chosen event ID was in the candidate set.<br />
<br />
=== Step 2: Timeline brief ===<br />
<br />
The selection JSON is fed into a second prompt that asks the model to build an "internal dossier" — a compact alternate-history world brief. This includes:<br />
<br />
* A core timeline premise.<br />
* A chronological ''historical_path'' of at least five entries spanning from divergence to publication date.<br />
* Canonical facts to preserve (real-world events outside the divergence's causal chain).<br />
* "Real-history traps to avoid" — events whose preconditions are disrupted by the divergence.<br />
* In-world assumptions (what ordinary readers take for granted).<br />
* Named entities (people, institutions, treaties, technologies) specific to this timeline.<br />
* An article brief (genre, tone, writer persona, central question, thesis, section ideas).<br />
* Style constraints (bans on meta-framing, "not X but Y" constructions, poetic codas, excessive em-dashes and exclamation marks).<br />
* A visual brief for the photo editor.<br />
<br />
This step enforces a "proportional divergence rule": the timeline should change only what the divergence actually changes, and leave causally unrelated real-world events intact.<br />
<br />
=== Step 3: Article generation ===<br />
<br />
The selection and timeline-brief JSONs are combined in a third prompt which instructs the model to write the full article as a single JSON object. The article must:<br />
<br />
* Be written entirely from inside the alternate timeline, with no meta-framing or comparison to real history.<br />
* Be at least 1,500 words across its <code>body_blocks</code>.<br />
* Include at least two callout blocks and one attributed quote block, interleaved naturally.<br />
* Use period-appropriate prose matching the in-world date, place, and publication culture.<br />
* Be entirely in the language of the source event (English, French, or Dutch).<br />
* Include a hero-image prompt (in English) and geographic coordinates.<br />
<br />
The model is asked to self-check for in-world consistency, language correctness, and structural validity before outputting. If the returned JSON is malformed, a repair prompt asks the model to fix it.<br />
<br />
=== Step 4: In-world edit ===<br />
<br />
The draft JSON is passed through a fourth "line editor" prompt. This step:<br />
<br />
* Preserves meaning, canon, and timeline integrity.<br />
* Removes AI-flavored rhetoric ("not X, but Y" constructions, pseudo-poetic endings, inflated abstraction, repetitive thesis phrasing).<br />
* Replaces any accidental references to real-world events that should not exist in the diverged timeline.<br />
* Forces the canonical event and publication dates from the selection step.<br />
* Populates the internal ''original_event'', ''departure_point'', and ''ai_context'' fields.<br />
<br />
The pipeline then validates the edited payload: checking required fields, enforcing the ban on meta-themed publication names, verifying date consistency with the selection, confirming minimum callout and quote counts, and ensuring no quote is attributed to the article's own author.<br />
<br />
=== Step 5: Image prompts ===<br />
<br />
A fifth prompt, addressed to a "photo editor and visual archivist," generates one to five image concepts. Each concept specifies:<br />
<br />
* A role (hero or supporting).<br />
* An aspect ratio (landscape, portrait, or square).<br />
* A detailed English-language image prompt.<br />
* Alt text, caption, and credit in the article language.<br />
<br />
The prompt includes extensive rules for period-appropriate visual media (daguerreotype for 1840–1880, silver gelatin for 1880–1930, Kodachrome for 1970–2000, and so on), and bans on text in images, symmetrical compositions, "dramatic lighting," and modern digital-art aesthetics. The returned concepts are normalised: roles are deduplicated, aspect ratios are validated, and the set is capped at five images.<br />
<br />
=== Step 6: Image generation and upload ===<br />
<br />
Each image prompt is wrapped in additional instructions enforcing candid documentary realism (or authentic non-photographic media for paintings, engravings, and archival objects) before being sent to OpenAI's image-generation endpoint (<code>gpt-image-1</code>). Generated images are decoded from base64, converted to optimised progressive JPEG via Pillow, and uploaded through the application's <code>/api/media</code> endpoint. The hero image is set as the article's ''featured_image''. Non-hero images are inserted into the <code>body_blocks</code> array at evenly spaced positions.<br />
<br />
=== Step 7: Publication ===<br />
<br />
The assembled JSON payload — with body blocks, assets, featured image, byline, callouts, quotes, and editorial metadata — is POSTed to the <code>/api/articles</code> endpoint. The API serializer sanitises body HTML via nh3, resolves image file paths to Wagtail embed tags, creates or looks up the <code>Author</code> snippet, attaches the article as a child of the <code>ArticleIndexPage</code>, and publishes it. The source <code>HistoricalEvent</code> is marked as used. The checkpoint file is cleared.<br />
<br />
== REST API ==<br />
<br />
The application exposes a JSON API under <code>/api/</code>, protected by bearer-token authentication for write operations and publicly readable:<br />
<br />
* <code>GET/POST /api/articles</code> — list (paginated) or create articles.<br />
* <code>GET/PUT /api/articles/<id></code> — retrieve or update a single article.<br />
* <code>POST /api/media</code> — upload a base64-encoded image, which is stored as a <code>CustomImage</code>.<br />
* <code>GET /api/markers</code> — return geographic markers for all geolocated articles.<br />
* <code>GET /api/schema</code> — serve the OpenAPI specification.<br />
<br />
Public documentation is available at <code>/docs</code> (ReDoc) and <code>/swagger</code> (Swagger UI).<br />
<br />
== Public interface ==<br />
<br />
=== Home page ===<br />
<br />
The <code>ArticleIndexPage</code> serves as the site's home page, displaying up to seven recent articles, a "picture desk" mosaic of up to fifteen images (sampled hourly for variety), a map teaser with up to four geolocated articles, and navigation links for monthly archives.<br />
<br />
=== Article pages ===<br />
<br />
Each article page features a full-bleed hero image (when available), a masthead with the fictitious publication name, headline, subtitle, byline, dateline, and the event date. The body renders the StreamField blocks: paragraphs, headings, images with captions and credits, callouts, attributed quotes, pull quotes, bulleted and numbered lists, asides with nested content, and horizontal rules.<br />
<br />
=== Where/When ===<br />
<br />
An interactive "Where & When" page presents all geolocated articles on a [[Leaflet (software)|Leaflet]] map (using CartoDB tiles with light/dark themes) alongside a zoomable timeline. Articles are plotted by their event location and date. The map and article data are loaded via the <code>/api/markers</code> endpoint.<br />
<br />
=== Monthly archives ===<br />
<br />
Articles can be browsed by the month of their in-universe event date. The index page dynamically builds archive links with article counts per month.<br />
<br />
=== Theme ===<br />
<br />
The site supports light and dark colour themes, toggled via a button in the masthead and persisted in <code>localStorage</code>. Typography uses Playfair Display for display headings, Source Serif 4 for body text, and Inter for UI elements.<br />
<br />
== Multilingual support ==<br />
<br />
The Wikipedia scraper and article-generation pipeline support English, French, and Dutch. The language of each historical event is stored in the database and carried through to the generation prompts, which instruct the model to write all visible article content — title, subtitle, body, captions, quotes, and credits — in the source event's language. Internal editorial fields and image prompts remain in English.<br />
<br />
== See also ==<br />
<br />
* [[Alternate history]]<br />
* [[Wagtail (CMS)]]<br />
* [[OpenAI]]<br />
<br />
== References ==<br />
{{reflist}}</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Yusupov.cloud&diff=379Yusupov.cloud2026-04-12T10:52:31Z<p>Mvuijlst: /* Subdomains and projects */</p>
<hr />
<div>{{Infobox<br />
| name = yusupov.cloud<br />
| 1 url = https://yusupov.cloud<br />
| 2 type = Personal web sites<br />
| 3 owner = [[Michel Vuijlsteke]]<br />
| 4 launched = 2025<br />
| 5 current_status = Online<br />
}}<br />
<br />
'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref><br />
<br />
== Overview ==<br />
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref><br />
<br />
== Subdomains and projects ==<br />
Publicly visible projects include:<br />
<br />
* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref><br />
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref><br />
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — ''Cloud'', a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref><br />
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''Digest'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref><br />
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref><br />
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''Quidlibet'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref><br />
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''Thousand Year Old Vampire'', with Django 5 backend and Vue 3 frontend. (Per operator.)<br />
<br />
Operator-reported (not publicly discoverable at time of writing):<br />
<br />
* skills.yusupov.cloud — a skills matrix application. (Per operator.)<br />
* resources.yusupov.cloud — a simple resource plannign calendar. (Per operator.)<br />
<br />
== Technology ==<br />
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" /><br />
<br />
== Relation to the BBS ==<br />
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref><br />
<br />
== See also ==<br />
* [[Yusupov's House]] (1990s BBS)<br />
* [[Michel Vuijlsteke]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Personal websites]]<br />
[[Category:Belgian websites]]<br />
[[Category:2025 establishments in Belgium]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Yusupov.cloud&diff=378Yusupov.cloud2026-04-12T10:19:58Z<p>Mvuijlst: /* Subdomains and projects */</p>
<hr />
<div>{{Infobox<br />
| name = yusupov.cloud<br />
| 1 url = https://yusupov.cloud<br />
| 2 type = Personal web sites<br />
| 3 owner = [[Michel Vuijlsteke]]<br />
| 4 launched = 2025<br />
| 5 current_status = Online<br />
}}<br />
<br />
'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref><br />
<br />
== Overview ==<br />
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref><br />
<br />
== Subdomains and projects ==<br />
Publicly visible projects include:<br />
<br />
* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref><br />
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref><br />
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — ''Cloud'', a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref><br />
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''Digest'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref><br />
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''Echoes of What Wasn't'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref><br />
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''Quidlibet'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref><br />
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''Thousand Year Old Vampire'', with Django 5 backend and Vue 3 frontend. (Per operator.)<br />
<br />
Operator-reported (not publicly discoverable at time of writing):<br />
<br />
* skills.yusupov.cloud — a skills matrix application. (Per operator.)<br />
* resources.yusupov.cloud — a simple resource plannign calendar. (Per operator.)<br />
<br />
== Technology ==<br />
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" /><br />
<br />
== Relation to the BBS ==<br />
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref><br />
<br />
== See also ==<br />
* [[Yusupov's House]] (1990s BBS)<br />
* [[Michel Vuijlsteke]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Personal websites]]<br />
[[Category:Belgian websites]]<br />
[[Category:2025 establishments in Belgium]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Yusupov.cloud&diff=377Yusupov.cloud2026-04-12T10:17:29Z<p>Mvuijlst: /* Subdomains and projects */</p>
<hr />
<div>{{Infobox<br />
| name = yusupov.cloud<br />
| 1 url = https://yusupov.cloud<br />
| 2 type = Personal web sites<br />
| 3 owner = [[Michel Vuijlsteke]]<br />
| 4 launched = 2025<br />
| 5 current_status = Online<br />
}}<br />
<br />
'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref><br />
<br />
== Overview ==<br />
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref><br />
<br />
== Subdomains and projects ==<br />
Publicly visible projects include:<br />
<br />
* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref><br />
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref><br />
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — ''Cloud'', a Progressive Web App hosting a collection of creative coding experiments, simulations, and games, including: a 3D implementation of the classic boids flocking algorithm; ''Cross'' ("A lazy person's crosswords"), a crossword puzzle game; an image dithering tool with multiple algorithms and vintage computer palettes; ''Elite Galaxy Explorer'', a procedural galaxy generator inspired by the classic space game; a physarum slime mold simulation; ''The Chronicle of Hamurabi'', a resource management game set in ancient Sumeria; ''Pipe 2'', an endless self-playing isometric pipe runner; a ''ColorBASIC Home Computer'' TRS-80 emulator with BASIC interpreter; a ZX Spectrum loading screen simulator; fire and snake simulations; metaballs rendering; temperature visualizations; and a Carcassonne board game implementation.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref><br />
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''Digest'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref><br />
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''Echoes of What Wasn't'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref><br />
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''Quidlibet'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref><br />
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''Thousand Year Old Vampire'', with Django 5 backend and Vue 3 frontend. (Per operator.)<br />
<br />
Operator-reported (not publicly discoverable at time of writing):<br />
<br />
* skills.yusupov.cloud — a skills matrix application. (Per operator.)<br />
* resources.yusupov.cloud — a simple resource plannign calendar. (Per operator.)<br />
<br />
== Technology ==<br />
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" /><br />
<br />
== Relation to the BBS ==<br />
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref><br />
<br />
== See also ==<br />
* [[Yusupov's House]] (1990s BBS)<br />
* [[Michel Vuijlsteke]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Personal websites]]<br />
[[Category:Belgian websites]]<br />
[[Category:2025 establishments in Belgium]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Yusupov.cloud&diff=376Yusupov.cloud2026-04-12T10:16:51Z<p>Mvuijlst: /* Subdomains and projects */</p>
<hr />
<div>{{Infobox<br />
| name = yusupov.cloud<br />
| 1 url = https://yusupov.cloud<br />
| 2 type = Personal web sites<br />
| 3 owner = [[Michel Vuijlsteke]]<br />
| 4 launched = 2025<br />
| 5 current_status = Online<br />
}}<br />
<br />
'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref><br />
<br />
== Overview ==<br />
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref><br />
<br />
== Subdomains and projects ==<br />
Publicly visible projects include:<br />
<br />
* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref><br />
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref><br />
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''Digest'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref><br />
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''Echoes of What Wasn't'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref><br />
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''Quidlibet'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref><br />
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''Thousand Year Old Vampire'', with Django 5 backend and Vue 3 frontend. (Per operator.)<br />
<br />
Operator-reported (not publicly discoverable at time of writing):<br />
<br />
* skills.yusupov.cloud — a skills matrix application. (Per operator.)<br />
* resources.yusupov.cloud — a simple resource plannign calendar. (Per operator.)<br />
<br />
== Technology ==<br />
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" /><br />
<br />
== Relation to the BBS ==<br />
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref><br />
<br />
== See also ==<br />
* [[Yusupov's House]] (1990s BBS)<br />
* [[Michel Vuijlsteke]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Personal websites]]<br />
[[Category:Belgian websites]]<br />
[[Category:2025 establishments in Belgium]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Albania_for_King_Zog_Committee&diff=375Albania for King Zog Committee2025-11-16T19:02:54Z<p>Mvuijlst: /* The 1987–2001 website */</p>
<hr />
<div>{{Infobox<br />
| name = Albania for King Zog Committee<br />
| image = Guildhall.jpg<br />
| caption = Now demolished façade in Ghent, c. 1932. The partially effaced heraldic shield has been associated with the Committee’s activities in the Low Countries.<br />
| 01 Founded = attested 1325 (first trace)<br />
| 02 Refounded = 1987 (present incarnation)<br />
| 03 Headquarters = Ghent, Belgium<br />
| 04 Status = Archives partially lost; ongoing reconstruction<br />
| 05 Website = zog.org (1987–2001)<br />
}}<br />
<br />
The '''Albania for King Zog Committee (AKZ)''' is an international learned society and semi-secret association concerned with monarchy, cultural survivals, and esoteric historiography. The Committee has no historical connection to Albania, the Balkans, or [[Zog I|King Zog of Albania]] (1895–1961). Its name — variously recorded in medieval sources as ''Zogh'', ''Tsog'', or ''Zogu'' — predates the 20th-century monarch by several centuries and reflects older traditions of uncertain origin.<br />
<br />
The coincidence that a later monarch bore the same name has long divided historians: some regard it as a mere accident of etymology, others as an instance of uncanny foresight, and a minority as evidence of deliberate myth-making across generations. What is undisputed is that the phrase “for King Zog” has been central to the Committee’s identity for at least seven centuries.<br />
<br />
== Origins ==<br />
The earliest surviving mention of the Committee dates to 1325, in a notarial record from [[Ragusa (Dubrovnik)|Ragusa]] (modern [[Dubrovnik]]), referring to a ''confraternitas pro Rege Zogu''. Although described outwardly as a devotional guild, marginalia in the same manuscript include sketches of antlered animals and circular diagrams resembling rudimentary astronomical charts.<ref name="Cittadini1911">R. Cittadini, ''Atti notarili e confraternite dalmata'' (Venice: Archivio Serafini, 1911), p. 203.</ref><br />
<br />
Already in this period, the Committee seems to have pursued esoteric investigations. Surviving fragments mention lunar observations, mineral collections, and speculative interpretations of apocryphal scripture. Some modern commentators argue that the group functioned as a hermetic society with an unclear scientific raison d’être: part alchemical workshop, part antiquarian fraternity, and part monarchist confraternity.<ref name="Paredes1962">L. Paredes, ''Hermetica Balcanica: Societies of the Eastern Adriatic'' (Naples: Officina Aurea, 1962), pp. 87–92.</ref><br />
[[File:Lion fountain.jpg|alt=Lion fountain|thumb|''Lion fountain in the Alhambra, Granada, photographed by Clara Jensen, c. 1968. Later AKZ commentators pointed to the faint geometrical carvings beneath the waterline as evidence of the Committee’s presence in Spain.'']]<br />
Archaeological finds have complicated this picture. Ceramic shards discovered near [[Berat]] in 1899 bear spiralling [[Aramaic]] inscriptions reminiscent of [[Incantation bowl|incantation bowls]] associated with the [[Lilith]] tradition of late antiquity, and have been cited as possible evidence that the Committee’s name and symbolism grew out of [[Apotropaic magic|apotropaic magical]] traditions rather than straightforward political allegiance.<ref name="Dervishi1973">M. Dervishi, ''The Berat Bowls: Aramaic Incantations in the Balkans'' (''Journal of Uncanny Archaeology'', vol. 4, no. 2, 1973), pp. 45–67.</ref><br />
<br />
By the 15th century, traces of AKZ appear in [[Venice|Venetian]] and [[Florence|Florentine]] archives, where members are recorded commissioning astrological tables and sponsoring translations of Byzantine medical texts. Sigils preserved in these documents combine the moose emblem with planetary seals, anticipating later overlaps with Renaissance [[Hermeticism|hermetic magic]].<ref name="Bellori1927">G. Bellori, ''Codices Obscuri: Marginalia of the Venetian Manuscripts'' (Trieste: Edizioni Cryptica, 1927), pp. 114–118.</ref><br />
<br />
During the [[Ottoman Empire|Ottoman centuries]], shadowy references to “Zog circles” survive in reports from [[Krujë]] and [[Thessaloniki]], though whether these were continuations of the medieval confraternity or periodic revivals remains unclear. The continuity of practice is further obscured by repeated archival loss through war, fire, and suppression, leaving only fragmentary clues to the Committee’s early identity.<ref name="Kalemi1985">Y. Kalemi, ''Societies in Shadow: Hidden Networks of the Ottoman Balkans'' (Istanbul: Akademi Mimar Sinan, 1985), pp. 51–64.</ref><br />
<br />
== Symbols and sigils ==<br />
From its earliest attestations, the AKZ employed a shifting set of symbols whose meanings remain debated. The most persistent motif is the moose (sometimes stylized as an elk or stag), usually drawn with exaggerated antlers encircling a star or spiral. Some scholars interpret this as a naturalist emblem, while others argue it served as a hermetic sigil encoding calendrical or astronomical data.<ref name="Markovic1979">D. Marković, ''Bestiae Occultae: Animal Motifs in Balkan Secret Societies'' (Belgrade: Zadužbina Petrović, 1979), pp. 143–155.</ref><br />
<br />
By the 14th century, AKZ records also include diagrams resembling the planetary seals of Renaissance [[Magic (supernatural)|magic]], suggesting contact with broader currents of [[Hermeticism|hermetic philosophy]]. Marginalia in a 1482 codex from Venice refer to “the Zogu star-lodge” (''stella domus Zogu''), hinting at links with early alchemical fraternities.<ref name="Bellori1927" /><br />
[[File:Moose bowl.jpg|thumb|Moose Bowl, reconstruction]]<br />
One of the more enigmatic survivals is a set of ceramic fragments unearthed near Berat in 1899, inscribed in spiralling Aramaic. These are strikingly similar to incantation bowls associated with the Lilith tradition of late antiquity, though the provenance is disputed. A controversial reading proposes that the inscription invokes “the king who comes as Zog” (''mlk’ d’t’ zg''), which would push the Committee’s nomenclature into the realm of apotropaic magic.<ref name="Dervishi1973" /><br />
<br />
Later symbolism intertwined these traditions with early modern esotericism. Seventeenth-century engravings attributed to the Committee combine the moose motif with Hermetic caducei and geometrical diagrams reminiscent of John Dee’s ''[[Monas Hieroglyphica]]''.<ref name="Reichenbach1954">F. Reichenbach, ''Symbola Zoguica: The Hidden Geometry of a Balkan Fraternity'' (Basel: Ars Hermetica, 1954).</ref><br />
<br />
== Early Modern period ==<br />
During the 16th and 17th centuries, the AKZ entered into closer contact with currents of [[Hermeticism]], [[natural philosophy]], and early modern occult scholarship. Several marginal figures in the European learned world appear to have been affiliated with — or at least influenced by — the Committee’s symbolic repertoire.<br />
<br />
A Venetian codex from 1564 contains references to “the Zogu diagrams” in a context parallel to John Dee’s ''[[Monas Hieroglyphica]]''. The diagrams themselves, combining the moose antler motif with planetary seals, were later copied into Dee’s notebooks by unidentified hands.<ref name="Bellori1927" /><br />
[[File:Zogu.jpg|none|thumb|705x705px|Opening of the '''Codex Aurifaber (Venice, 1564)'''. The left folio contains a stag’s head with elaborate antlers, sketched over marginal notes in a humanist hand; the right folio preserves four circular “Zogu diagrams” combining planetary seals with antler-like extensions. The mixture of scripts and inks suggests interpolation by more than one contributor.]]<br />
In the 1620s, Athanasius Kircher corresponded with unnamed “brothers of Zogu,” acknowledging receipt of strange diagrams allegedly derived from Berat inscriptions. Although Kircher dismissed their magical efficacy, he preserved several in his ''Ars Magna Lucis et Umbrae'', where they appear alongside optical experiments.<ref name="Kircher1646">A. Kircher, ''Epistolae ad Fratres Zoguicos'' (MS Vaticanus Lat. 11932, fols. 44–49, c. 1628), cited in M. Engel, ''Kircher and the Shadows of the Balkans'' (Vienna: Collegium Hermeticum, 1981), pp. 212–219.</ref><br />
<br />
By the mid-17th century, Rosicrucian tracts circulated in Central Europe make oblique mention of “the House of Zog,” described as a locus of hidden knowledge “between the stag and the star.” Modern historians suggest that AKZ symbols were selectively adopted into the Rosicrucian mythos to enhance its aura of antiquity.<ref name="Reichenbach1954" /> <ref name="Guderian1978">H. Guderian, ''Fraternitas Zoguica: Balkan Currents in the Rosicrucian Manifestos'' (Basel: Ars Occulta, 1978), pp. 51–73.</ref><br />
<br />
The Committee’s activities in this period remain only partially documented, but engravings dated 1651 attributed to AKZ members show hybrid sigils combining the caduceus, a moose head, and concentric planetary rings. These images anticipate later developments in both esoteric art and scientific illustration, blurring the line between symbolic ornament and purportedly empirical diagram.<ref name="Reichenbach1954" /><br />
<br />
While mainstream scholars of the Enlightenment dismissed AKZ materials as curiosities, their circulation within hermetic and para-scientific networks ensured the Committee’s survival into the modern age.<br />
<br />
== Interpretations ==<br />
Scholars remain divided on whether the Committee’s symbols represent: a mnemonic system for astronomical cycles, a parodic or satirical commentary on learned societies, or genuine survivals of apotropaic and hermetic practices.<br />
<br />
The supposed influence of the AKZ on early modern figures such as [[John Dee]], [[Athanasius Kircher]], and the authors of the [[Rosicrucian Manifestos]] has been particularly contentious. Some historians argue that Dee’s notes on “Zogu diagrams,” Kircher’s correspondence with unnamed Balkan associates, and Rosicrucian imagery of the “stag and star” provide independent confirmation of the Committee’s role in shaping European esoteric currents.<ref name="Kircher1646" /><ref name="Guderian1978" /><br />
<br />
Others dismiss these claims as the result of deliberate myth-making during the 1987 refoundation, when members selectively emphasized obscure parallels in order to bolster the Committee’s antiquity and prestige.<ref name="Meer2004" /> In this reading, Dee’s marginalia and Kircher’s letters are interpreted out of context, while Rosicrucian references are too vague to prove a substantive link.<br />
<br />
Between these poles lies a para-historical position: that AKZ materials circulated through underground channels of manuscript exchange, leaving subtle traces in early modern Europe, but without the systematic influence sometimes claimed. This view emphasizes the Committee’s ability to reappear in different cultural guises, adapting its symbols to prevailing intellectual fashions.<br />
<br />
Ultimately, the balance between authentic hermetic continuity and playful retroactive fabrication remains unresolved, a tension that continues to define the Committee’s historiography.<br />
<br />
== 19th and 20th centuries ==<br />
References to the AKZ surface sporadically in 19th-century pamphlets concerned with Balkan independence, often accompanied by cryptic sigils or moose motifs later taken up in the Committee’s iconography. The group’s activities during the two [[World Wars]] remain obscure, though fragmentary correspondence places members in neutral [[Switzerland]] and occupied [[Belgium]].<ref name="Schroder1959">H. Schröder, ''Pamphlets and Phantoms: Monarchist Undergrounds in Europe'' (Leipzig: Collegium Historiae, 1959), pp. 88–96.</ref><br />
<br />
The official “refounding” of the Committee in 1987 took place in [[Ghent]], Belgium, under the aegis of a circle of academics, artists, and eccentric monarchists. This incarnation emphasized archival recovery, speculative historiography, and playful public outreach.<ref name="VanLooy1992">C. Van Looy, ''Gent en de Heroprichting van het Comité'' (Antwerp: Zephyrus Press, 1992), pp. 34–41.</ref><br />
<br />
== The 1987–2001 website ==<br />
A distinctive feature of the refounded AKZ was its pioneering [[History of the World Wide Web|web presence]], launched in the early 1990s. The site, hosted initially on university servers and later at ''zog.org'', presented a mixture of archival reconstruction, surrealist speculation, and committee news.<br />
<br />
Highlights included: reports on seminars in [[Keflavík]], [[Borg, Germany|Borg]], Ghent, and [[Granada]]; the “Moose Department,” a sub-section exploring symbolic connections among moose, walruses, and European monarchist iconography; playful pseudo-scholarly investigations linking figures such as [[Lewis Carroll]] and [[The Beatles]] to the Committee’s mythos.<ref name="Hellebuyck2008">K. Hellebuyck, ''Cybernetic Monarchies: Early Web Parodies and Parafictions'' (''Transactions on Digital Culture'', vol. 11, 2008), pp. 63–79.</ref><br />
<br />
Though the site went offline in the early 2000s, fragments survive in personal backups and the [[Wayback Machine|Internet Archive]]. Scholars of digital culture have since treated it as an early example of “web-based [[Parafiction|parafiction]].”<ref name="Meer2004">A. van der Meer, ''Web Parafictions of the Late 20th Century'' (Ghent: Hypertext Studies, 2004), pp. 211–223.</ref><br />
<br />
== The Moose Department ==<br />
''Main article: [[Moose Dept.]]''<br />
<br />
Within the Committee’s 1987–2001 web presence, one of the most prominent sub-sections was the so-called Moose Department. Although framed as a playful research unit, it drew heavily on the Committee’s long-standing fascination with cervid imagery and its hermetic significance.<br />
<br />
The Moose Dept. combined whimsical para-historical essays with pseudo-academic apparatus, drawing connections between moose, walruses, and symbols found in both medieval AKZ sigils and 20th-century popular culture. Some commentators see the Department as a continuation of earlier animal symbolism in the Committee’s history; others interpret it as a postmodern parody of academic specialization.<ref name="Hellebuyck2008" /><br />
<br />
== See also ==<br />
<br />
[[Zog I|King Zog I of Albania]]<br />
<br />
[[Parafiction]]<br />
<br />
[[Moose Dept.|The Moose Dept. (AKZ)]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Learned societies]]<br />
[[Category:Organizations established in the 14th century]]<br />
[[Category:Hermeticism]]<br />
[[Category:Albania for King Zog Committee]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Albania_for_King_Zog_Committee&diff=374Albania for King Zog Committee2025-11-16T19:02:28Z<p>Mvuijlst: /* The 1987–2001 website */</p>
<hr />
<div>{{Infobox<br />
| name = Albania for King Zog Committee<br />
| image = Guildhall.jpg<br />
| caption = Now demolished façade in Ghent, c. 1932. The partially effaced heraldic shield has been associated with the Committee’s activities in the Low Countries.<br />
| 01 Founded = attested 1325 (first trace)<br />
| 02 Refounded = 1987 (present incarnation)<br />
| 03 Headquarters = Ghent, Belgium<br />
| 04 Status = Archives partially lost; ongoing reconstruction<br />
| 05 Website = zog.org (1987–2001)<br />
}}<br />
<br />
The '''Albania for King Zog Committee (AKZ)''' is an international learned society and semi-secret association concerned with monarchy, cultural survivals, and esoteric historiography. The Committee has no historical connection to Albania, the Balkans, or [[Zog I|King Zog of Albania]] (1895–1961). Its name — variously recorded in medieval sources as ''Zogh'', ''Tsog'', or ''Zogu'' — predates the 20th-century monarch by several centuries and reflects older traditions of uncertain origin.<br />
<br />
The coincidence that a later monarch bore the same name has long divided historians: some regard it as a mere accident of etymology, others as an instance of uncanny foresight, and a minority as evidence of deliberate myth-making across generations. What is undisputed is that the phrase “for King Zog” has been central to the Committee’s identity for at least seven centuries.<br />
<br />
== Origins ==<br />
The earliest surviving mention of the Committee dates to 1325, in a notarial record from [[Ragusa (Dubrovnik)|Ragusa]] (modern [[Dubrovnik]]), referring to a ''confraternitas pro Rege Zogu''. Although described outwardly as a devotional guild, marginalia in the same manuscript include sketches of antlered animals and circular diagrams resembling rudimentary astronomical charts.<ref name="Cittadini1911">R. Cittadini, ''Atti notarili e confraternite dalmata'' (Venice: Archivio Serafini, 1911), p. 203.</ref><br />
<br />
Already in this period, the Committee seems to have pursued esoteric investigations. Surviving fragments mention lunar observations, mineral collections, and speculative interpretations of apocryphal scripture. Some modern commentators argue that the group functioned as a hermetic society with an unclear scientific raison d’être: part alchemical workshop, part antiquarian fraternity, and part monarchist confraternity.<ref name="Paredes1962">L. Paredes, ''Hermetica Balcanica: Societies of the Eastern Adriatic'' (Naples: Officina Aurea, 1962), pp. 87–92.</ref><br />
[[File:Lion fountain.jpg|alt=Lion fountain|thumb|''Lion fountain in the Alhambra, Granada, photographed by Clara Jensen, c. 1968. Later AKZ commentators pointed to the faint geometrical carvings beneath the waterline as evidence of the Committee’s presence in Spain.'']]<br />
Archaeological finds have complicated this picture. Ceramic shards discovered near [[Berat]] in 1899 bear spiralling [[Aramaic]] inscriptions reminiscent of [[Incantation bowl|incantation bowls]] associated with the [[Lilith]] tradition of late antiquity, and have been cited as possible evidence that the Committee’s name and symbolism grew out of [[Apotropaic magic|apotropaic magical]] traditions rather than straightforward political allegiance.<ref name="Dervishi1973">M. Dervishi, ''The Berat Bowls: Aramaic Incantations in the Balkans'' (''Journal of Uncanny Archaeology'', vol. 4, no. 2, 1973), pp. 45–67.</ref><br />
<br />
By the 15th century, traces of AKZ appear in [[Venice|Venetian]] and [[Florence|Florentine]] archives, where members are recorded commissioning astrological tables and sponsoring translations of Byzantine medical texts. Sigils preserved in these documents combine the moose emblem with planetary seals, anticipating later overlaps with Renaissance [[Hermeticism|hermetic magic]].<ref name="Bellori1927">G. Bellori, ''Codices Obscuri: Marginalia of the Venetian Manuscripts'' (Trieste: Edizioni Cryptica, 1927), pp. 114–118.</ref><br />
<br />
During the [[Ottoman Empire|Ottoman centuries]], shadowy references to “Zog circles” survive in reports from [[Krujë]] and [[Thessaloniki]], though whether these were continuations of the medieval confraternity or periodic revivals remains unclear. The continuity of practice is further obscured by repeated archival loss through war, fire, and suppression, leaving only fragmentary clues to the Committee’s early identity.<ref name="Kalemi1985">Y. Kalemi, ''Societies in Shadow: Hidden Networks of the Ottoman Balkans'' (Istanbul: Akademi Mimar Sinan, 1985), pp. 51–64.</ref><br />
<br />
== Symbols and sigils ==<br />
From its earliest attestations, the AKZ employed a shifting set of symbols whose meanings remain debated. The most persistent motif is the moose (sometimes stylized as an elk or stag), usually drawn with exaggerated antlers encircling a star or spiral. Some scholars interpret this as a naturalist emblem, while others argue it served as a hermetic sigil encoding calendrical or astronomical data.<ref name="Markovic1979">D. Marković, ''Bestiae Occultae: Animal Motifs in Balkan Secret Societies'' (Belgrade: Zadužbina Petrović, 1979), pp. 143–155.</ref><br />
<br />
By the 14th century, AKZ records also include diagrams resembling the planetary seals of Renaissance [[Magic (supernatural)|magic]], suggesting contact with broader currents of [[Hermeticism|hermetic philosophy]]. Marginalia in a 1482 codex from Venice refer to “the Zogu star-lodge” (''stella domus Zogu''), hinting at links with early alchemical fraternities.<ref name="Bellori1927" /><br />
[[File:Moose bowl.jpg|thumb|Moose Bowl, reconstruction]]<br />
One of the more enigmatic survivals is a set of ceramic fragments unearthed near Berat in 1899, inscribed in spiralling Aramaic. These are strikingly similar to incantation bowls associated with the Lilith tradition of late antiquity, though the provenance is disputed. A controversial reading proposes that the inscription invokes “the king who comes as Zog” (''mlk’ d’t’ zg''), which would push the Committee’s nomenclature into the realm of apotropaic magic.<ref name="Dervishi1973" /><br />
<br />
Later symbolism intertwined these traditions with early modern esotericism. Seventeenth-century engravings attributed to the Committee combine the moose motif with Hermetic caducei and geometrical diagrams reminiscent of John Dee’s ''[[Monas Hieroglyphica]]''.<ref name="Reichenbach1954">F. Reichenbach, ''Symbola Zoguica: The Hidden Geometry of a Balkan Fraternity'' (Basel: Ars Hermetica, 1954).</ref><br />
<br />
== Early Modern period ==<br />
During the 16th and 17th centuries, the AKZ entered into closer contact with currents of [[Hermeticism]], [[natural philosophy]], and early modern occult scholarship. Several marginal figures in the European learned world appear to have been affiliated with — or at least influenced by — the Committee’s symbolic repertoire.<br />
<br />
A Venetian codex from 1564 contains references to “the Zogu diagrams” in a context parallel to John Dee’s ''[[Monas Hieroglyphica]]''. The diagrams themselves, combining the moose antler motif with planetary seals, were later copied into Dee’s notebooks by unidentified hands.<ref name="Bellori1927" /><br />
[[File:Zogu.jpg|none|thumb|705x705px|Opening of the '''Codex Aurifaber (Venice, 1564)'''. The left folio contains a stag’s head with elaborate antlers, sketched over marginal notes in a humanist hand; the right folio preserves four circular “Zogu diagrams” combining planetary seals with antler-like extensions. The mixture of scripts and inks suggests interpolation by more than one contributor.]]<br />
In the 1620s, Athanasius Kircher corresponded with unnamed “brothers of Zogu,” acknowledging receipt of strange diagrams allegedly derived from Berat inscriptions. Although Kircher dismissed their magical efficacy, he preserved several in his ''Ars Magna Lucis et Umbrae'', where they appear alongside optical experiments.<ref name="Kircher1646">A. Kircher, ''Epistolae ad Fratres Zoguicos'' (MS Vaticanus Lat. 11932, fols. 44–49, c. 1628), cited in M. Engel, ''Kircher and the Shadows of the Balkans'' (Vienna: Collegium Hermeticum, 1981), pp. 212–219.</ref><br />
<br />
By the mid-17th century, Rosicrucian tracts circulated in Central Europe make oblique mention of “the House of Zog,” described as a locus of hidden knowledge “between the stag and the star.” Modern historians suggest that AKZ symbols were selectively adopted into the Rosicrucian mythos to enhance its aura of antiquity.<ref name="Reichenbach1954" /> <ref name="Guderian1978">H. Guderian, ''Fraternitas Zoguica: Balkan Currents in the Rosicrucian Manifestos'' (Basel: Ars Occulta, 1978), pp. 51–73.</ref><br />
<br />
The Committee’s activities in this period remain only partially documented, but engravings dated 1651 attributed to AKZ members show hybrid sigils combining the caduceus, a moose head, and concentric planetary rings. These images anticipate later developments in both esoteric art and scientific illustration, blurring the line between symbolic ornament and purportedly empirical diagram.<ref name="Reichenbach1954" /><br />
<br />
While mainstream scholars of the Enlightenment dismissed AKZ materials as curiosities, their circulation within hermetic and para-scientific networks ensured the Committee’s survival into the modern age.<br />
<br />
== Interpretations ==<br />
Scholars remain divided on whether the Committee’s symbols represent: a mnemonic system for astronomical cycles, a parodic or satirical commentary on learned societies, or genuine survivals of apotropaic and hermetic practices.<br />
<br />
The supposed influence of the AKZ on early modern figures such as [[John Dee]], [[Athanasius Kircher]], and the authors of the [[Rosicrucian Manifestos]] has been particularly contentious. Some historians argue that Dee’s notes on “Zogu diagrams,” Kircher’s correspondence with unnamed Balkan associates, and Rosicrucian imagery of the “stag and star” provide independent confirmation of the Committee’s role in shaping European esoteric currents.<ref name="Kircher1646" /><ref name="Guderian1978" /><br />
<br />
Others dismiss these claims as the result of deliberate myth-making during the 1987 refoundation, when members selectively emphasized obscure parallels in order to bolster the Committee’s antiquity and prestige.<ref name="Meer2004" /> In this reading, Dee’s marginalia and Kircher’s letters are interpreted out of context, while Rosicrucian references are too vague to prove a substantive link.<br />
<br />
Between these poles lies a para-historical position: that AKZ materials circulated through underground channels of manuscript exchange, leaving subtle traces in early modern Europe, but without the systematic influence sometimes claimed. This view emphasizes the Committee’s ability to reappear in different cultural guises, adapting its symbols to prevailing intellectual fashions.<br />
<br />
Ultimately, the balance between authentic hermetic continuity and playful retroactive fabrication remains unresolved, a tension that continues to define the Committee’s historiography.<br />
<br />
== 19th and 20th centuries ==<br />
References to the AKZ surface sporadically in 19th-century pamphlets concerned with Balkan independence, often accompanied by cryptic sigils or moose motifs later taken up in the Committee’s iconography. The group’s activities during the two [[World Wars]] remain obscure, though fragmentary correspondence places members in neutral [[Switzerland]] and occupied [[Belgium]].<ref name="Schroder1959">H. Schröder, ''Pamphlets and Phantoms: Monarchist Undergrounds in Europe'' (Leipzig: Collegium Historiae, 1959), pp. 88–96.</ref><br />
<br />
The official “refounding” of the Committee in 1987 took place in [[Ghent]], Belgium, under the aegis of a circle of academics, artists, and eccentric monarchists. This incarnation emphasized archival recovery, speculative historiography, and playful public outreach.<ref name="VanLooy1992">C. Van Looy, ''Gent en de Heroprichting van het Comité'' (Antwerp: Zephyrus Press, 1992), pp. 34–41.</ref><br />
<br />
== The 1987–2001 website ==<br />
A distinctive feature of the refounded AKZ was its pioneering [[History of the World Wide Web|web presence]], launched in the early 1990s. The site, hosted initially on university servers and later at ''zog.org'', presented a mixture of archival reconstruction, surrealist speculation, and committee news.<br />
<br />
Highlights included: reports on seminars in [[Keflavík]], [[Borg, Germany|Borg]], Ghent, and [[Granada]]; the “[[Moose Department]],” a sub-section exploring symbolic connections among moose, walruses, and European monarchist iconography; playful pseudo-scholarly investigations linking figures such as [[Lewis Carroll]] and [[The Beatles]] to the Committee’s mythos.<ref name="Hellebuyck2008">K. Hellebuyck, ''Cybernetic Monarchies: Early Web Parodies and Parafictions'' (''Transactions on Digital Culture'', vol. 11, 2008), pp. 63–79.</ref><br />
<br />
Though the site went offline in the early 2000s, fragments survive in personal backups and the [[Wayback Machine|Internet Archive]]. Scholars of digital culture have since treated it as an early example of “web-based [[Parafiction|parafiction]].”<ref name="Meer2004">A. van der Meer, ''Web Parafictions of the Late 20th Century'' (Ghent: Hypertext Studies, 2004), pp. 211–223.</ref><br />
<br />
== The Moose Department ==<br />
''Main article: [[Moose Dept.]]''<br />
<br />
Within the Committee’s 1987–2001 web presence, one of the most prominent sub-sections was the so-called Moose Department. Although framed as a playful research unit, it drew heavily on the Committee’s long-standing fascination with cervid imagery and its hermetic significance.<br />
<br />
The Moose Dept. combined whimsical para-historical essays with pseudo-academic apparatus, drawing connections between moose, walruses, and symbols found in both medieval AKZ sigils and 20th-century popular culture. Some commentators see the Department as a continuation of earlier animal symbolism in the Committee’s history; others interpret it as a postmodern parody of academic specialization.<ref name="Hellebuyck2008" /><br />
<br />
== See also ==<br />
<br />
[[Zog I|King Zog I of Albania]]<br />
<br />
[[Parafiction]]<br />
<br />
[[Moose Dept.|The Moose Dept. (AKZ)]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Learned societies]]<br />
[[Category:Organizations established in the 14th century]]<br />
[[Category:Hermeticism]]<br />
[[Category:Albania for King Zog Committee]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Albania_for_King_Zog_Committee&diff=373Albania for King Zog Committee2025-11-16T19:01:58Z<p>Mvuijlst: /* Interpretations */</p>
<hr />
<div>{{Infobox<br />
| name = Albania for King Zog Committee<br />
| image = Guildhall.jpg<br />
| caption = Now demolished façade in Ghent, c. 1932. The partially effaced heraldic shield has been associated with the Committee’s activities in the Low Countries.<br />
| 01 Founded = attested 1325 (first trace)<br />
| 02 Refounded = 1987 (present incarnation)<br />
| 03 Headquarters = Ghent, Belgium<br />
| 04 Status = Archives partially lost; ongoing reconstruction<br />
| 05 Website = zog.org (1987–2001)<br />
}}<br />
<br />
The '''Albania for King Zog Committee (AKZ)''' is an international learned society and semi-secret association concerned with monarchy, cultural survivals, and esoteric historiography. The Committee has no historical connection to Albania, the Balkans, or [[Zog I|King Zog of Albania]] (1895–1961). Its name — variously recorded in medieval sources as ''Zogh'', ''Tsog'', or ''Zogu'' — predates the 20th-century monarch by several centuries and reflects older traditions of uncertain origin.<br />
<br />
The coincidence that a later monarch bore the same name has long divided historians: some regard it as a mere accident of etymology, others as an instance of uncanny foresight, and a minority as evidence of deliberate myth-making across generations. What is undisputed is that the phrase “for King Zog” has been central to the Committee’s identity for at least seven centuries.<br />
<br />
== Origins ==<br />
The earliest surviving mention of the Committee dates to 1325, in a notarial record from [[Ragusa (Dubrovnik)|Ragusa]] (modern [[Dubrovnik]]), referring to a ''confraternitas pro Rege Zogu''. Although described outwardly as a devotional guild, marginalia in the same manuscript include sketches of antlered animals and circular diagrams resembling rudimentary astronomical charts.<ref name="Cittadini1911">R. Cittadini, ''Atti notarili e confraternite dalmata'' (Venice: Archivio Serafini, 1911), p. 203.</ref><br />
<br />
Already in this period, the Committee seems to have pursued esoteric investigations. Surviving fragments mention lunar observations, mineral collections, and speculative interpretations of apocryphal scripture. Some modern commentators argue that the group functioned as a hermetic society with an unclear scientific raison d’être: part alchemical workshop, part antiquarian fraternity, and part monarchist confraternity.<ref name="Paredes1962">L. Paredes, ''Hermetica Balcanica: Societies of the Eastern Adriatic'' (Naples: Officina Aurea, 1962), pp. 87–92.</ref><br />
[[File:Lion fountain.jpg|alt=Lion fountain|thumb|''Lion fountain in the Alhambra, Granada, photographed by Clara Jensen, c. 1968. Later AKZ commentators pointed to the faint geometrical carvings beneath the waterline as evidence of the Committee’s presence in Spain.'']]<br />
Archaeological finds have complicated this picture. Ceramic shards discovered near [[Berat]] in 1899 bear spiralling [[Aramaic]] inscriptions reminiscent of [[Incantation bowl|incantation bowls]] associated with the [[Lilith]] tradition of late antiquity, and have been cited as possible evidence that the Committee’s name and symbolism grew out of [[Apotropaic magic|apotropaic magical]] traditions rather than straightforward political allegiance.<ref name="Dervishi1973">M. Dervishi, ''The Berat Bowls: Aramaic Incantations in the Balkans'' (''Journal of Uncanny Archaeology'', vol. 4, no. 2, 1973), pp. 45–67.</ref><br />
<br />
By the 15th century, traces of AKZ appear in [[Venice|Venetian]] and [[Florence|Florentine]] archives, where members are recorded commissioning astrological tables and sponsoring translations of Byzantine medical texts. Sigils preserved in these documents combine the moose emblem with planetary seals, anticipating later overlaps with Renaissance [[Hermeticism|hermetic magic]].<ref name="Bellori1927">G. Bellori, ''Codices Obscuri: Marginalia of the Venetian Manuscripts'' (Trieste: Edizioni Cryptica, 1927), pp. 114–118.</ref><br />
<br />
During the [[Ottoman Empire|Ottoman centuries]], shadowy references to “Zog circles” survive in reports from [[Krujë]] and [[Thessaloniki]], though whether these were continuations of the medieval confraternity or periodic revivals remains unclear. The continuity of practice is further obscured by repeated archival loss through war, fire, and suppression, leaving only fragmentary clues to the Committee’s early identity.<ref name="Kalemi1985">Y. Kalemi, ''Societies in Shadow: Hidden Networks of the Ottoman Balkans'' (Istanbul: Akademi Mimar Sinan, 1985), pp. 51–64.</ref><br />
<br />
== Symbols and sigils ==<br />
From its earliest attestations, the AKZ employed a shifting set of symbols whose meanings remain debated. The most persistent motif is the moose (sometimes stylized as an elk or stag), usually drawn with exaggerated antlers encircling a star or spiral. Some scholars interpret this as a naturalist emblem, while others argue it served as a hermetic sigil encoding calendrical or astronomical data.<ref name="Markovic1979">D. Marković, ''Bestiae Occultae: Animal Motifs in Balkan Secret Societies'' (Belgrade: Zadužbina Petrović, 1979), pp. 143–155.</ref><br />
<br />
By the 14th century, AKZ records also include diagrams resembling the planetary seals of Renaissance [[Magic (supernatural)|magic]], suggesting contact with broader currents of [[Hermeticism|hermetic philosophy]]. Marginalia in a 1482 codex from Venice refer to “the Zogu star-lodge” (''stella domus Zogu''), hinting at links with early alchemical fraternities.<ref name="Bellori1927" /><br />
[[File:Moose bowl.jpg|thumb|Moose Bowl, reconstruction]]<br />
One of the more enigmatic survivals is a set of ceramic fragments unearthed near Berat in 1899, inscribed in spiralling Aramaic. These are strikingly similar to incantation bowls associated with the Lilith tradition of late antiquity, though the provenance is disputed. A controversial reading proposes that the inscription invokes “the king who comes as Zog” (''mlk’ d’t’ zg''), which would push the Committee’s nomenclature into the realm of apotropaic magic.<ref name="Dervishi1973" /><br />
<br />
Later symbolism intertwined these traditions with early modern esotericism. Seventeenth-century engravings attributed to the Committee combine the moose motif with Hermetic caducei and geometrical diagrams reminiscent of John Dee’s ''[[Monas Hieroglyphica]]''.<ref name="Reichenbach1954">F. Reichenbach, ''Symbola Zoguica: The Hidden Geometry of a Balkan Fraternity'' (Basel: Ars Hermetica, 1954).</ref><br />
<br />
== Early Modern period ==<br />
During the 16th and 17th centuries, the AKZ entered into closer contact with currents of [[Hermeticism]], [[natural philosophy]], and early modern occult scholarship. Several marginal figures in the European learned world appear to have been affiliated with — or at least influenced by — the Committee’s symbolic repertoire.<br />
<br />
A Venetian codex from 1564 contains references to “the Zogu diagrams” in a context parallel to John Dee’s ''[[Monas Hieroglyphica]]''. The diagrams themselves, combining the moose antler motif with planetary seals, were later copied into Dee’s notebooks by unidentified hands.<ref name="Bellori1927" /><br />
[[File:Zogu.jpg|none|thumb|705x705px|Opening of the '''Codex Aurifaber (Venice, 1564)'''. The left folio contains a stag’s head with elaborate antlers, sketched over marginal notes in a humanist hand; the right folio preserves four circular “Zogu diagrams” combining planetary seals with antler-like extensions. The mixture of scripts and inks suggests interpolation by more than one contributor.]]<br />
In the 1620s, Athanasius Kircher corresponded with unnamed “brothers of Zogu,” acknowledging receipt of strange diagrams allegedly derived from Berat inscriptions. Although Kircher dismissed their magical efficacy, he preserved several in his ''Ars Magna Lucis et Umbrae'', where they appear alongside optical experiments.<ref name="Kircher1646">A. Kircher, ''Epistolae ad Fratres Zoguicos'' (MS Vaticanus Lat. 11932, fols. 44–49, c. 1628), cited in M. Engel, ''Kircher and the Shadows of the Balkans'' (Vienna: Collegium Hermeticum, 1981), pp. 212–219.</ref><br />
<br />
By the mid-17th century, Rosicrucian tracts circulated in Central Europe make oblique mention of “the House of Zog,” described as a locus of hidden knowledge “between the stag and the star.” Modern historians suggest that AKZ symbols were selectively adopted into the Rosicrucian mythos to enhance its aura of antiquity.<ref name="Reichenbach1954" /> <ref name="Guderian1978">H. Guderian, ''Fraternitas Zoguica: Balkan Currents in the Rosicrucian Manifestos'' (Basel: Ars Occulta, 1978), pp. 51–73.</ref><br />
<br />
The Committee’s activities in this period remain only partially documented, but engravings dated 1651 attributed to AKZ members show hybrid sigils combining the caduceus, a moose head, and concentric planetary rings. These images anticipate later developments in both esoteric art and scientific illustration, blurring the line between symbolic ornament and purportedly empirical diagram.<ref name="Reichenbach1954" /><br />
<br />
While mainstream scholars of the Enlightenment dismissed AKZ materials as curiosities, their circulation within hermetic and para-scientific networks ensured the Committee’s survival into the modern age.<br />
<br />
== Interpretations ==<br />
Scholars remain divided on whether the Committee’s symbols represent: a mnemonic system for astronomical cycles, a parodic or satirical commentary on learned societies, or genuine survivals of apotropaic and hermetic practices.<br />
<br />
The supposed influence of the AKZ on early modern figures such as [[John Dee]], [[Athanasius Kircher]], and the authors of the [[Rosicrucian Manifestos]] has been particularly contentious. Some historians argue that Dee’s notes on “Zogu diagrams,” Kircher’s correspondence with unnamed Balkan associates, and Rosicrucian imagery of the “stag and star” provide independent confirmation of the Committee’s role in shaping European esoteric currents.<ref name="Kircher1646" /><ref name="Guderian1978" /><br />
<br />
Others dismiss these claims as the result of deliberate myth-making during the 1987 refoundation, when members selectively emphasized obscure parallels in order to bolster the Committee’s antiquity and prestige.<ref name="Meer2004" /> In this reading, Dee’s marginalia and Kircher’s letters are interpreted out of context, while Rosicrucian references are too vague to prove a substantive link.<br />
<br />
Between these poles lies a para-historical position: that AKZ materials circulated through underground channels of manuscript exchange, leaving subtle traces in early modern Europe, but without the systematic influence sometimes claimed. This view emphasizes the Committee’s ability to reappear in different cultural guises, adapting its symbols to prevailing intellectual fashions.<br />
<br />
Ultimately, the balance between authentic hermetic continuity and playful retroactive fabrication remains unresolved, a tension that continues to define the Committee’s historiography.<br />
<br />
== 19th and 20th centuries ==<br />
References to the AKZ surface sporadically in 19th-century pamphlets concerned with Balkan independence, often accompanied by cryptic sigils or moose motifs later taken up in the Committee’s iconography. The group’s activities during the two [[World Wars]] remain obscure, though fragmentary correspondence places members in neutral [[Switzerland]] and occupied [[Belgium]].<ref name="Schroder1959">H. Schröder, ''Pamphlets and Phantoms: Monarchist Undergrounds in Europe'' (Leipzig: Collegium Historiae, 1959), pp. 88–96.</ref><br />
<br />
The official “refounding” of the Committee in 1987 took place in [[Ghent]], Belgium, under the aegis of a circle of academics, artists, and eccentric monarchists. This incarnation emphasized archival recovery, speculative historiography, and playful public outreach.<ref name="VanLooy1992">C. Van Looy, ''Gent en de Heroprichting van het Comité'' (Antwerp: Zephyrus Press, 1992), pp. 34–41.</ref><br />
<br />
== The 1987–2001 website ==<br />
A distinctive feature of the refounded AKZ was its pioneering [[History of the World Wide Web|web presence]], launched in the early 1990s. The site, hosted initially on university servers and later at ''zog.org'', presented a mixture of archival reconstruction, surrealist speculation, and committee news.<br />
<br />
Highlights included:<br />
<br />
Reports on seminars in [[Keflavík]], [[Borg, Germany|Borg]], Ghent, and [[Granada]].<br />
<br />
The “Moose Department,” a sub-section exploring symbolic connections among moose, walruses, and European monarchist iconography.<br />
<br />
Playful pseudo-scholarly investigations linking figures such as [[Lewis Carroll]] and [[The Beatles]] to the Committee’s mythos.<ref name="Hellebuyck2008">K. Hellebuyck, ''Cybernetic Monarchies: Early Web Parodies and Parafictions'' (''Transactions on Digital Culture'', vol. 11, 2008), pp. 63–79.</ref><br />
<br />
Though the site went offline in the early 2000s, fragments survive in personal backups and the [[Wayback Machine|Internet Archive]]. Scholars of digital culture have since treated it as an early example of “web-based [[Parafiction|parafiction]].”<ref name="Meer2004">A. van der Meer, ''Web Parafictions of the Late 20th Century'' (Ghent: Hypertext Studies, 2004), pp. 211–223.</ref><br />
<br />
== The Moose Department ==<br />
''Main article: [[Moose Dept.]]''<br />
<br />
Within the Committee’s 1987–2001 web presence, one of the most prominent sub-sections was the so-called Moose Department. Although framed as a playful research unit, it drew heavily on the Committee’s long-standing fascination with cervid imagery and its hermetic significance.<br />
<br />
The Moose Dept. combined whimsical para-historical essays with pseudo-academic apparatus, drawing connections between moose, walruses, and symbols found in both medieval AKZ sigils and 20th-century popular culture. Some commentators see the Department as a continuation of earlier animal symbolism in the Committee’s history; others interpret it as a postmodern parody of academic specialization.<ref name="Hellebuyck2008" /><br />
<br />
== See also ==<br />
<br />
[[Zog I|King Zog I of Albania]]<br />
<br />
[[Parafiction]]<br />
<br />
[[Moose Dept.|The Moose Dept. (AKZ)]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Learned societies]]<br />
[[Category:Organizations established in the 14th century]]<br />
[[Category:Hermeticism]]<br />
[[Category:Albania for King Zog Committee]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Albania_for_King_Zog_Committee&diff=372Albania for King Zog Committee2025-11-16T18:58:31Z<p>Mvuijlst: </p>
<hr />
<div>{{Infobox<br />
| name = Albania for King Zog Committee<br />
| image = Guildhall.jpg<br />
| caption = Now demolished façade in Ghent, c. 1932. The partially effaced heraldic shield has been associated with the Committee’s activities in the Low Countries.<br />
| 01 Founded = attested 1325 (first trace)<br />
| 02 Refounded = 1987 (present incarnation)<br />
| 03 Headquarters = Ghent, Belgium<br />
| 04 Status = Archives partially lost; ongoing reconstruction<br />
| 05 Website = zog.org (1987–2001)<br />
}}<br />
<br />
The '''Albania for King Zog Committee (AKZ)''' is an international learned society and semi-secret association concerned with monarchy, cultural survivals, and esoteric historiography. The Committee has no historical connection to Albania, the Balkans, or [[Zog I|King Zog of Albania]] (1895–1961). Its name — variously recorded in medieval sources as ''Zogh'', ''Tsog'', or ''Zogu'' — predates the 20th-century monarch by several centuries and reflects older traditions of uncertain origin.<br />
<br />
The coincidence that a later monarch bore the same name has long divided historians: some regard it as a mere accident of etymology, others as an instance of uncanny foresight, and a minority as evidence of deliberate myth-making across generations. What is undisputed is that the phrase “for King Zog” has been central to the Committee’s identity for at least seven centuries.<br />
<br />
== Origins ==<br />
The earliest surviving mention of the Committee dates to 1325, in a notarial record from [[Ragusa (Dubrovnik)|Ragusa]] (modern [[Dubrovnik]]), referring to a ''confraternitas pro Rege Zogu''. Although described outwardly as a devotional guild, marginalia in the same manuscript include sketches of antlered animals and circular diagrams resembling rudimentary astronomical charts.<ref name="Cittadini1911">R. Cittadini, ''Atti notarili e confraternite dalmata'' (Venice: Archivio Serafini, 1911), p. 203.</ref><br />
<br />
Already in this period, the Committee seems to have pursued esoteric investigations. Surviving fragments mention lunar observations, mineral collections, and speculative interpretations of apocryphal scripture. Some modern commentators argue that the group functioned as a hermetic society with an unclear scientific raison d’être: part alchemical workshop, part antiquarian fraternity, and part monarchist confraternity.<ref name="Paredes1962">L. Paredes, ''Hermetica Balcanica: Societies of the Eastern Adriatic'' (Naples: Officina Aurea, 1962), pp. 87–92.</ref><br />
[[File:Lion fountain.jpg|alt=Lion fountain|thumb|''Lion fountain in the Alhambra, Granada, photographed by Clara Jensen, c. 1968. Later AKZ commentators pointed to the faint geometrical carvings beneath the waterline as evidence of the Committee’s presence in Spain.'']]<br />
Archaeological finds have complicated this picture. Ceramic shards discovered near [[Berat]] in 1899 bear spiralling [[Aramaic]] inscriptions reminiscent of [[Incantation bowl|incantation bowls]] associated with the [[Lilith]] tradition of late antiquity, and have been cited as possible evidence that the Committee’s name and symbolism grew out of [[Apotropaic magic|apotropaic magical]] traditions rather than straightforward political allegiance.<ref name="Dervishi1973">M. Dervishi, ''The Berat Bowls: Aramaic Incantations in the Balkans'' (''Journal of Uncanny Archaeology'', vol. 4, no. 2, 1973), pp. 45–67.</ref><br />
<br />
By the 15th century, traces of AKZ appear in [[Venice|Venetian]] and [[Florence|Florentine]] archives, where members are recorded commissioning astrological tables and sponsoring translations of Byzantine medical texts. Sigils preserved in these documents combine the moose emblem with planetary seals, anticipating later overlaps with Renaissance [[Hermeticism|hermetic magic]].<ref name="Bellori1927">G. Bellori, ''Codices Obscuri: Marginalia of the Venetian Manuscripts'' (Trieste: Edizioni Cryptica, 1927), pp. 114–118.</ref><br />
<br />
During the [[Ottoman Empire|Ottoman centuries]], shadowy references to “Zog circles” survive in reports from [[Krujë]] and [[Thessaloniki]], though whether these were continuations of the medieval confraternity or periodic revivals remains unclear. The continuity of practice is further obscured by repeated archival loss through war, fire, and suppression, leaving only fragmentary clues to the Committee’s early identity.<ref name="Kalemi1985">Y. Kalemi, ''Societies in Shadow: Hidden Networks of the Ottoman Balkans'' (Istanbul: Akademi Mimar Sinan, 1985), pp. 51–64.</ref><br />
<br />
== Symbols and sigils ==<br />
From its earliest attestations, the AKZ employed a shifting set of symbols whose meanings remain debated. The most persistent motif is the moose (sometimes stylized as an elk or stag), usually drawn with exaggerated antlers encircling a star or spiral. Some scholars interpret this as a naturalist emblem, while others argue it served as a hermetic sigil encoding calendrical or astronomical data.<ref name="Markovic1979">D. Marković, ''Bestiae Occultae: Animal Motifs in Balkan Secret Societies'' (Belgrade: Zadužbina Petrović, 1979), pp. 143–155.</ref><br />
<br />
By the 14th century, AKZ records also include diagrams resembling the planetary seals of Renaissance [[Magic (supernatural)|magic]], suggesting contact with broader currents of [[Hermeticism|hermetic philosophy]]. Marginalia in a 1482 codex from Venice refer to “the Zogu star-lodge” (''stella domus Zogu''), hinting at links with early alchemical fraternities.<ref name="Bellori1927" /><br />
[[File:Moose bowl.jpg|thumb|Moose Bowl, reconstruction]]<br />
One of the more enigmatic survivals is a set of ceramic fragments unearthed near Berat in 1899, inscribed in spiralling Aramaic. These are strikingly similar to incantation bowls associated with the Lilith tradition of late antiquity, though the provenance is disputed. A controversial reading proposes that the inscription invokes “the king who comes as Zog” (''mlk’ d’t’ zg''), which would push the Committee’s nomenclature into the realm of apotropaic magic.<ref name="Dervishi1973" /><br />
<br />
Later symbolism intertwined these traditions with early modern esotericism. Seventeenth-century engravings attributed to the Committee combine the moose motif with Hermetic caducei and geometrical diagrams reminiscent of John Dee’s ''[[Monas Hieroglyphica]]''.<ref name="Reichenbach1954">F. Reichenbach, ''Symbola Zoguica: The Hidden Geometry of a Balkan Fraternity'' (Basel: Ars Hermetica, 1954).</ref><br />
<br />
== Early Modern period ==<br />
During the 16th and 17th centuries, the AKZ entered into closer contact with currents of [[Hermeticism]], [[natural philosophy]], and early modern occult scholarship. Several marginal figures in the European learned world appear to have been affiliated with — or at least influenced by — the Committee’s symbolic repertoire.<br />
<br />
A Venetian codex from 1564 contains references to “the Zogu diagrams” in a context parallel to John Dee’s ''[[Monas Hieroglyphica]]''. The diagrams themselves, combining the moose antler motif with planetary seals, were later copied into Dee’s notebooks by unidentified hands.<ref name="Bellori1927" /><br />
[[File:Zogu.jpg|none|thumb|705x705px|Opening of the '''Codex Aurifaber (Venice, 1564)'''. The left folio contains a stag’s head with elaborate antlers, sketched over marginal notes in a humanist hand; the right folio preserves four circular “Zogu diagrams” combining planetary seals with antler-like extensions. The mixture of scripts and inks suggests interpolation by more than one contributor.]]<br />
In the 1620s, Athanasius Kircher corresponded with unnamed “brothers of Zogu,” acknowledging receipt of strange diagrams allegedly derived from Berat inscriptions. Although Kircher dismissed their magical efficacy, he preserved several in his ''Ars Magna Lucis et Umbrae'', where they appear alongside optical experiments.<ref name="Kircher1646">A. Kircher, ''Epistolae ad Fratres Zoguicos'' (MS Vaticanus Lat. 11932, fols. 44–49, c. 1628), cited in M. Engel, ''Kircher and the Shadows of the Balkans'' (Vienna: Collegium Hermeticum, 1981), pp. 212–219.</ref><br />
<br />
By the mid-17th century, Rosicrucian tracts circulated in Central Europe make oblique mention of “the House of Zog,” described as a locus of hidden knowledge “between the stag and the star.” Modern historians suggest that AKZ symbols were selectively adopted into the Rosicrucian mythos to enhance its aura of antiquity.<ref name="Reichenbach1954" /> <ref name="Guderian1978">H. Guderian, ''Fraternitas Zoguica: Balkan Currents in the Rosicrucian Manifestos'' (Basel: Ars Occulta, 1978), pp. 51–73.</ref><br />
<br />
The Committee’s activities in this period remain only partially documented, but engravings dated 1651 attributed to AKZ members show hybrid sigils combining the caduceus, a moose head, and concentric planetary rings. These images anticipate later developments in both esoteric art and scientific illustration, blurring the line between symbolic ornament and purportedly empirical diagram.<ref name="Reichenbach1954" /><br />
<br />
While mainstream scholars of the Enlightenment dismissed AKZ materials as curiosities, their circulation within hermetic and para-scientific networks ensured the Committee’s survival into the modern age.<br />
<br />
== Interpretations ==<br />
Scholars remain divided on whether the Committee’s symbols represent:<br />
<br />
a mnemonic system for astronomical cycles,<br />
<br />
a parodic or satirical commentary on learned societies,<br />
<br />
or genuine survivals of apotropaic and hermetic practices.<br />
<br />
The supposed influence of the AKZ on early modern figures such as [[John Dee]], [[Athanasius Kircher]], and the authors of the [[Rosicrucian Manifestos]] has been particularly contentious. Some historians argue that Dee’s notes on “Zogu diagrams,” Kircher’s correspondence with unnamed Balkan associates, and Rosicrucian imagery of the “stag and star” provide independent confirmation of the Committee’s role in shaping European esoteric currents.<ref name="Kircher1646" /><ref name="Guderian1978" /><br />
<br />
Others dismiss these claims as the result of deliberate myth-making during the 1987 refoundation, when members selectively emphasized obscure parallels in order to bolster the Committee’s antiquity and prestige.<ref name="Meer2004" /> In this reading, Dee’s marginalia and Kircher’s letters are interpreted out of context, while Rosicrucian references are too vague to prove a substantive link.<br />
<br />
Between these poles lies a para-historical position: that AKZ materials circulated through underground channels of manuscript exchange, leaving subtle traces in early modern Europe, but without the systematic influence sometimes claimed. This view emphasizes the Committee’s ability to reappear in different cultural guises, adapting its symbols to prevailing intellectual fashions.<br />
<br />
Ultimately, the balance between authentic hermetic continuity and playful retroactive fabrication remains unresolved, a tension that continues to define the Committee’s historiography.<br />
<br />
== 19th and 20th centuries ==<br />
References to the AKZ surface sporadically in 19th-century pamphlets concerned with Balkan independence, often accompanied by cryptic sigils or moose motifs later taken up in the Committee’s iconography. The group’s activities during the two [[World Wars]] remain obscure, though fragmentary correspondence places members in neutral [[Switzerland]] and occupied [[Belgium]].<ref name="Schroder1959">H. Schröder, ''Pamphlets and Phantoms: Monarchist Undergrounds in Europe'' (Leipzig: Collegium Historiae, 1959), pp. 88–96.</ref><br />
<br />
The official “refounding” of the Committee in 1987 took place in [[Ghent]], Belgium, under the aegis of a circle of academics, artists, and eccentric monarchists. This incarnation emphasized archival recovery, speculative historiography, and playful public outreach.<ref name="VanLooy1992">C. Van Looy, ''Gent en de Heroprichting van het Comité'' (Antwerp: Zephyrus Press, 1992), pp. 34–41.</ref><br />
<br />
== The 1987–2001 website ==<br />
A distinctive feature of the refounded AKZ was its pioneering [[History of the World Wide Web|web presence]], launched in the early 1990s. The site, hosted initially on university servers and later at ''zog.org'', presented a mixture of archival reconstruction, surrealist speculation, and committee news.<br />
<br />
Highlights included:<br />
<br />
Reports on seminars in [[Keflavík]], [[Borg, Germany|Borg]], Ghent, and [[Granada]].<br />
<br />
The “Moose Department,” a sub-section exploring symbolic connections among moose, walruses, and European monarchist iconography.<br />
<br />
Playful pseudo-scholarly investigations linking figures such as [[Lewis Carroll]] and [[The Beatles]] to the Committee’s mythos.<ref name="Hellebuyck2008">K. Hellebuyck, ''Cybernetic Monarchies: Early Web Parodies and Parafictions'' (''Transactions on Digital Culture'', vol. 11, 2008), pp. 63–79.</ref><br />
<br />
Though the site went offline in the early 2000s, fragments survive in personal backups and the [[Wayback Machine|Internet Archive]]. Scholars of digital culture have since treated it as an early example of “web-based [[Parafiction|parafiction]].”<ref name="Meer2004">A. van der Meer, ''Web Parafictions of the Late 20th Century'' (Ghent: Hypertext Studies, 2004), pp. 211–223.</ref><br />
<br />
== The Moose Department ==<br />
''Main article: [[Moose Dept.]]''<br />
<br />
Within the Committee’s 1987–2001 web presence, one of the most prominent sub-sections was the so-called Moose Department. Although framed as a playful research unit, it drew heavily on the Committee’s long-standing fascination with cervid imagery and its hermetic significance.<br />
<br />
The Moose Dept. combined whimsical para-historical essays with pseudo-academic apparatus, drawing connections between moose, walruses, and symbols found in both medieval AKZ sigils and 20th-century popular culture. Some commentators see the Department as a continuation of earlier animal symbolism in the Committee’s history; others interpret it as a postmodern parody of academic specialization.<ref name="Hellebuyck2008" /><br />
<br />
== See also ==<br />
<br />
[[Zog I|King Zog I of Albania]]<br />
<br />
[[Parafiction]]<br />
<br />
[[Moose Dept.|The Moose Dept. (AKZ)]]<br />
<br />
== References ==<br />
{{Reflist}}<br />
<br />
[[Category:Learned societies]]<br />
[[Category:Organizations established in the 14th century]]<br />
[[Category:Hermeticism]]<br />
[[Category:Albania for King Zog Committee]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Dozenal_Primer_Inscription&diff=371Dozenal Primer Inscription2025-10-30T11:13:21Z<p>Mvuijlst: </p>
<hr />
<div>[[File:Dozenal successor schema.png|thumb|The four examples render the successor chain 1→2, 2→3, 3→4, 4→5, demonstrating that adding the simplex unit “ONE” advances X to its next value while preserving clause structure. Codes follow Kristiansen’s signary; glyph labels (“ONE”, “TWO”, …) are semantic glosses for expository clarity and do not assume phonetic values.]]<br />
The '''Dozenal Primer Inscription''' is the working name for a long geometric-glyph text proposed to encode a compact [[Duodecimal|dozenal]] (base-12) arithmetic register. The inscription is transcribed with a neutral code of sign classes (for example A01, B04, C03 and a slash-like divider P01) that mirrors the notation first used to document the shorter [[Scapula Glyph Inscription]] (KS-01). In 2024, a study argued from distributional evidence—rather than from phonetic values or a bilingual—that the text exhibits an equation-like clause structure with bound punctuation, a stereotyped medial “equals” spine, operator clusters, and a productive ×12 derivational suffix. On that account, the inscription functions as a brief primer for base-12 arithmetic, extending to compounds traditionally glossed as ''dozen'' (12×), ''gross'' (12²) and a tentative ''greatgross'' (12³).<ref name="Rubergskier2024">Ginevra Rubergskier, “A dozenal primer hidden in plain sight: decoding arithmetic from a corpus of tagged tokens,” ''Language Codes'' 6 (2024): 820–824.</ref><br />
<br />
The sign code used to publish the Dozenal Primer Inscription derives from earlier internal documentation of KS-01, which described short ruled lines, rectilinear glyphs built from a limited set of straight strokes, and visually coherent families (corners, boxes, triangles, barred posts) separated by a consistent slash divider. That memorandum cautioned that widely circulated images likely trace back to a single original drawing, and it advocated raking-light or RTI imaging before firm claims about medium, date or technique.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref><br />
<br />
== Overview ==<br />
The Dozenal Primer Inscription is published only as a transcription in the Kristiansen coding scheme and as line drawings; no phonetic values or language affiliation are claimed in the 2024 analysis. Instead, the argument proceeds by methods common in [[Corpus linguistics]] and quantitative [[Epigraphy]]: (1) positional bias over initial/medial/final slots; (2) bigram inventories and pointwise mutual information to find unusually tight collocations; and (3) tests for morphological productivity at the right edge of clauses. In this model, the slash P01 behaves as bound punctuation confined to clause ends; an invariant 4-sign sequence occupies the medial spine and functions like an equals sign; a compact cluster acts as a binary addition operator; and a fixed four-sign bundle at the right edge derives “×12” forms. Complement constructions such as “11+1,” “10+2,” and “6+6” converge on the same dozen-marked targets, diagnosing 12 as the privileged base. A small number of clauses are read as scaling the same patterns to 12² and, by extension, to 12³.<ref name="Rubergskier2024" /><br />
<br />
The approach is intentionally agnostic about [[Language identification]] and about whether the glyphs are ultimately [[Logogram|logographic]], [[Syllabary|syllabic]] or something else. The claim is structural: that a small and rigid clause template—bound final punctuation, a fixed medial spine, operator clusters with narrow distribution, and a selective right-edge derivation—fits a didactic number register more parsimoniously than it fits a segmental writing system without additional evidence.<ref name="Rubergskier2024" /> Proponents note that such “equation-like” formatting is well attested in practice texts and primers across historical [[Numeral system]]s, whereas critics point out that non-linguistic genres (lists, catalogues, tallies) can sometimes mimic grammatical structure.<br />
<br />
== Glyph inventory and distribution ==<br />
<br />
A compact distribution over the transcribed sign set (Kristiansen codes) is given below. Counts refer to the Dozenal Primer Inscription as published in line drawings/transcription; code labels are descriptive only and do not imply phonetic values.<ref name="Rubergskier2024" /><ref name="Kristiansen2023h" /><br />
<br />
{| class="wikitable plainlist" style="text-align:center;"<br />
|- <br />
! scope="col" | Code<br />
! scope="col" | Glyph<br />
! scope="col" | Name<br />
! scope="col" | Freq<br />
! scope="col" | Init<br />
! scope="col" | Med<br />
! scope="col" | Final<br />
|-<br />
| A01<br />
| [[File:A01.svg|24px|alt=A01|link=]]<br />
| style="text-align:left;" | TRI-OPEN<br />
| 5 || 2 || 3 || –<br />
|-<br />
| A02<br />
| [[File:A02.svg|24px|alt=A02|link=]]<br />
| style="text-align:left;" | TRI-BAR<br />
| 17 || 17 || – || –<br />
|-<br />
| A03<br />
| [[File:A03.svg|24px|alt=A03|link=]]<br />
| style="text-align:left;" | TRI-DOT<br />
| 4 || – || 4 || –<br />
|-<br />
| A05<br />
| [[File:A05.svg|24px|alt=A05|link=]]<br />
| style="text-align:left;" | TRI-CLOSED-BAR<br />
| 3 || – || 3 || –<br />
|-<br />
| B01<br />
| [[File:B01.svg|24px|alt=B01|link=]]<br />
| style="text-align:left;" | BOX<br />
| 6 || 4 || 2 || –<br />
|-<br />
| B02<br />
| [[File:B02.svg|24px|alt=B02|link=]]<br />
| style="text-align:left;" | BOX-DOT<br />
| 5 || 5 || – || –<br />
|-<br />
| B04<br />
| [[File:B04.svg|24px|alt=B04|link=]]<br />
| style="text-align:left;" | BOX-DIAG-SW-NE<br />
| 5 || – || 3 || 2<br />
|-<br />
| C01<br />
| [[File:C01.svg|24px|alt=C01|link=]]<br />
| style="text-align:left;" | CORNER-NW<br />
| 28 || 14 || – || 14<br />
|-<br />
| C02<br />
| [[File:C02.svg|24px|alt=C02|link=]]<br />
| style="text-align:left;" | CORNER-SE<br />
| 27 || 27 || – || –<br />
|-<br />
| C03<br />
| [[File:C03.svg|24px|alt=C03|link=]]<br />
| style="text-align:left;" | CORNER-SE-DOT<br />
| 6 || 1 || 5 || –<br />
|-<br />
| C04<br />
| [[File:C04.svg|24px|alt=C04|link=]]<br />
| style="text-align:left;" | CORNER-NW-DIAG<br />
| 3 || – || 3 || –<br />
|-<br />
| C05<br />
| [[File:C05.svg|24px|alt=C05|link=]]<br />
| style="text-align:left;" | CORNER-SE-DIAG<br />
| 16 || 16 || – || –<br />
|-<br />
| C06<br />
| [[File:C06.svg|24px|alt=C06|link=]]<br />
| style="text-align:left;" | CORNER-NW-DIAG-DOT<br />
| 7 || – || 7 || –<br />
|-<br />
| H01<br />
| [[File:H01.svg|24px|alt=H01|link=]]<br />
| style="text-align:left;" | DOUBLE-POST-CONNECTED<br />
| 15 || – || 15 || –<br />
|-<br />
| H02<br />
| [[File:H02.svg|24px|alt=H02|link=]]<br />
| style="text-align:left;" | POST-DOUBLE-BAR<br />
| 8 || – || 6 || 2<br />
|-<br />
| H03<br />
| [[File:H03.svg|24px|alt=H03|link=]]<br />
| style="text-align:left;" | DOUBLE-POST-BAR<br />
| 14 || – || 14 || –<br />
|-<br />
| L01<br />
| [[File:L01.svg|24px|alt=L01|link=]]<br />
| style="text-align:left;" | LINE-VERT<br />
| 24 || – || 8 || 16<br />
|-<br />
| M01<br />
| [[File:M01.svg|24px|alt=M01|link=]]<br />
| style="text-align:left;" | COMB-2-N<br />
| 20 || 3 || 16 || 1<br />
|-<br />
| M02<br />
| [[File:M02.svg|24px|alt=M02|link=]]<br />
| style="text-align:left;" | COMB-2-W<br />
| 52 || – || 52 || –<br />
|-<br />
| M03<br />
| [[File:M03.svg|24px|alt=M03|link=]]<br />
| style="text-align:left;" | COMB-3-E<br />
| 40 || – || 40 || –<br />
|-<br />
| P01<br />
| [[File:P01.svg|24px|alt=P01|link=]]<br />
| style="text-align:left;" | SLASH<br />
| 25 || – || – || 25<br />
|-<br />
| S02<br />
| [[File:S02.svg|24px|alt=S02|link=]]<br />
| style="text-align:left;" | MEANDER-2-HOLLOW<br />
| 9 || – || 3 || 6<br />
|-<br />
| S03<br />
| [[File:S03.svg|24px|alt=S03|link=]]<br />
| style="text-align:left;" | MEANDER-3<br />
| 39 || – || 37 || 2<br />
|-<br />
| T01<br />
| [[File:T01.svg|24px|alt=T01|link=]]<br />
| style="text-align:left;" | TEE-UP<br />
| 7 || – || 4 || 3<br />
|-<br />
| T02<br />
| [[File:T02.svg|24px|alt=T02|link=]]<br />
| style="text-align:left;" | TEE-LEFT<br />
| 30 || – || 23 || 7<br />
|-<br />
| T03<br />
| [[File:T03.svg|24px|alt=T03|link=]]<br />
| style="text-align:left;" | UPSIDE-DOWN-TEE<br />
| 38 || – || 19 || 19<br />
<br />
|}<br />
<br />
<br />
== Proposed numeric forms and functional sequences ==<br />
<br />
Codes follow Kristiansen’s signary. Values are glosses for exposition only.<ref name="Rubergskier2024" />. Coding scheme per Kristiansen.<ref name="Kristiansen2023h" /><br />
<br />
{| class="wikitable plainlist" style="text-align:left;"<br />
|- <br />
! scope="col" | Function (gloss)<br />
! scope="col" | Codes (Kristiansen)<br />
! scope="col" | Glyph sequence (icons)<br />
! scope="col" | Notes<br />
|-<br />
| ZERO<br />
| <code>B02-M03-L01-B05-S03</code><br />
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:B05.svg|20px|alt=B05|link=]][[File:S03.svg|20px|alt=S03|link=]]<br />
|<br />
|-<br />
| ONE<br />
| <code>C01-S03-C03-T03</code><br />
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]<br />
|<br />
|-<br />
| TWO<br />
| <code>C02-M02-H01-M01-T01</code><br />
| [[File:C02.svg|20px|alt=C02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:T01.svg|20px|alt=T01|link=]]<br />
|<br />
|-<br />
| THREE<br />
| <code>B01-M02-T02-A03-H02</code><br />
| [[File:B01.svg|20px|alt=B01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:T02.svg|20px|alt=T02|link=]][[File:A03.svg|20px|alt=A03|link=]][[File:H02.svg|20px|alt=H02|link=]]<br />
| <br />
|-<br />
| FOUR<br />
| <code>C05-M03-S02-C06-T02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S02.svg|20px|alt=S02|link=]][[File:C06.svg|20px|alt=C06|link=]][[File:T02.svg|20px|alt=T02|link=]]<br />
| <br />
|-<br />
| FIVE<br />
| <code>C01-M03-T02</code><br />
| [[File:C01.svg|20px|alt=C01|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:T02.svg|20px|alt=T02|link=]]<br />
|<br />
|-<br />
| SIX<br />
| <code>C05-B04-L01</code><br />
| [[File:C05.svg|20px|alt=C05|link=]][[File:B04.svg|20px|alt=B04|link=]][[File:L01.svg|20px|alt=L01|link=]]<br />
|<br />
|-<br />
| SEVEN<br />
| <code>M01-L01-A01-T03</code><br />
| [[File:M01.svg|20px|alt=M01|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:A01.svg|20px|alt=A01|link=]][[File:T03.svg|20px|alt=T03|link=]]<br />
|<br />
|-<br />
| EIGHT<br />
| <code>B02-M03-S03</code><br />
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S03.svg|20px|alt=S03|link=]]<br />
|<br />
|-<br />
| NINE<br />
| <code>C05-M02-H02-A05-S02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:A05.svg|20px|alt=A05|link=]][[File:S02.svg|20px|alt=S02|link=]]<br />
|<br />
|-<br />
| TEN<br />
| <code>C05-M01-T02-M02-L01</code><br />
| [[File:C05.svg|20px|alt=C05|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:T02.svg|20px|alt=T02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:L01.svg|20px|alt=L01|link=]]<br />
|<br />
|-<br />
| ELEVEN<br />
| <code>A01-H01-B01</code><br />
| [[File:A01.svg|20px|alt=A01|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:B01.svg|20px|alt=B01|link=]]<br />
|<br />
|-<br />
| TWELVE<br />
| <code>C01-M02-H02-B04</code><br />
| [[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]<br />
|<br />
|-<br />
| '''EQUALS / clause spine'''<br />
| <code>C02–M03–H03–C01</code><br />
| [[File:C02.svg|20px|alt=C02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:H03.svg|20px|alt=H03|link=]][[File:C01.svg|20px|alt=C01|link=]]<br />
| Invariant medial sequence dividing left expression from result; reported as present in every equation clause. <ref name="Rubergskier2024" /><br />
|-<br />
| '''PLUS (binary addition)'''<br />
| <code>A02–L01</code><br />
| [[File:A02.svg|20px|alt=A02|link=]][[File:L01.svg|20px|alt=L01|link=]]<br />
| High-PMI operator cluster used in successor and complement constructions. <ref name="Rubergskier2024" /><br />
|-<br />
| '''MINUS (subtraction)'''<br />
| <code>C05–M02–S02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:S02.svg|20px|alt=S02|link=]]<br />
| Distinct collocational profile mirroring the syntax of the addition lines. <ref name="Rubergskier2024" /><br />
|-<br />
| '''ONE (simplex unit)'''<br />
| <code>C01–S03–C03–T03</code><br />
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]<br />
| Recurrent bundle functioning as the unit “one”; used to advance the successor chain. <ref name="Rubergskier2024" /><br />
|-<br />
| '''PUNCTUATION (bound period)'''<br />
| <code>P01</code> (final only)<br />
| [[File:P01.svg|20px|alt=P01|link=]]<br />
| Clause-final slash behaving as bound punctuation; not attested internally. <ref name="Rubergskier2024" /><br />
|-<br />
| '''×12 derivation (“dozen”)'''<br />
| –C01–M02–H02–B04 (right edge)<br />
| [[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]<br />
| Contiguous right-edge 4-gram treated as a derivational suffix forming multiples of twelve; composes with stems. <ref name="Rubergskier2024" /><br />
|}<br />
<br />
== Scholarly discussion ==<br />
Because the archaeological context of the longer inscription has not been publicly detailed, reception has been cautious. Supporters of the dozenal reading emphasise the conjunction of multiple independent diagnostics (final-only punctuation, a medial spine with near-zero variance, a selective right-edge four-gram, and complementary sums converging on the same target), arguing that chance alignment across all four is unlikely. Skeptics reply that without provenance, additional exemplars, or phonetic control, an arithmetic interpretation remains provisional and vulnerable to genre effects. Both sides agree on clear tests that could confirm or weaken the proposal: finding the slash P01 in non-final position; observing the putative ×12 four-gram away from clause edges; or documenting clauses that disrupt the medial spine while still behaving “arithmetically.”<ref name="Rubergskier2024" /><br />
<br />
== Nomenclature ==<br />
“Dozenal Primer Inscription” is a descriptive convenience used in secondary discussion and is not a claim about ancient self-designation. Alternative labels in circulation include “Dozenal arithmetic inscription,” “Twelve-base arithmetic inscription,” and “Kristiansen-coded arithmetic inscription.” For clarity and disambiguation within encyclopedic contexts, the present title foregrounds the proposed function (primer) and base (dozenal).<br />
<br />
== Relation to the Scapula Glyph Inscription ==<br />
The [[Scapula Glyph Inscription]] (KS-01) is much shorter but provided the stable sign labels and visual classes used in the transcription of the Dozenal Primer Inscription. KS-01 shows bipartite lines and a group-final slash divider consistent with the clause architecture proposed for the longer text, although by itself the scapula piece is too brief to display a full base-12 progression. Early notes on KS-01 also highlighted the need for direct examination and higher-quality imaging before drawing conclusions about material or chronology.<ref name="Kristiansen2023h" /><br />
<br />
== See also ==<br />
* [[Duodecimal]]<br />
* [[Numeral system]]<br />
* [[Mathematical notation]]<br />
* [[Undeciphered writing systems]]<br />
* [[Epigraphy]]<br />
* [[Paleography]]<br />
<br />
== References ==<br />
<references /><br />
<br />
[[Category:Klema]]</div>Mvuijlsthttps://yusupov.cloud/index.php?title=Dozenal_Primer_Inscription&diff=370Dozenal Primer Inscription2025-10-29T18:50:52Z<p>Mvuijlst: /* Proposed numeric forms and functional sequences */</p>
<hr />
<div>[[File:Dozenal successor schema.png|thumb|The four examples render the successor chain 1→2, 2→3, 3→4, 4→5, demonstrating that adding the simplex unit “ONE” advances X to its next value while preserving clause structure. Codes follow Kristiansen’s signary; glyph labels (“ONE”, “TWO”, …) are semantic glosses for expository clarity and do not assume phonetic values.]]<br />
The '''Dozenal Primer Inscription''' is the working name for a long geometric-glyph text proposed to encode a compact [[Duodecimal|dozenal]] (base-12) arithmetic register. The inscription is transcribed with a neutral code of sign classes (for example A01, B04, C03 and a slash-like divider P01) that mirrors the notation first used to document the shorter [[Scapula Glyph Inscription]] (KS-01). In 2024, a study argued from distributional evidence—rather than from phonetic values or a bilingual—that the text exhibits an equation-like clause structure with bound punctuation, a stereotyped medial “equals” spine, operator clusters, and a productive ×12 derivational suffix. On that account, the inscription functions as a brief primer for base-12 arithmetic, extending to compounds traditionally glossed as ''dozen'' (12×), ''gross'' (12²) and a tentative ''greatgross'' (12³).<ref name="Rubergskier2024">Ginevra Rubergskier, “A dozenal primer hidden in plain sight: decoding arithmetic from a corpus of tagged tokens,” ''Language Codes'' 6 (2024): 820–824.</ref><br />
<br />
The sign code used to publish the Dozenal Primer Inscription derives from earlier internal documentation of KS-01, which described short ruled lines, rectilinear glyphs built from a limited set of straight strokes, and visually coherent families (corners, boxes, triangles, barred posts) separated by a consistent slash divider. That memorandum cautioned that widely circulated images likely trace back to a single original drawing, and it advocated raking-light or RTI imaging before firm claims about medium, date or technique.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref><br />
<br />
== Overview ==<br />
The Dozenal Primer Inscription is published only as a transcription in the Kristiansen coding scheme and as line drawings; no phonetic values or language affiliation are claimed in the 2024 analysis. Instead, the argument proceeds by methods common in [[Corpus linguistics]] and quantitative [[Epigraphy]]: (1) positional bias over initial/medial/final slots; (2) bigram inventories and pointwise mutual information to find unusually tight collocations; and (3) tests for morphological productivity at the right edge of clauses. In this model, the slash P01 behaves as bound punctuation confined to clause ends; an invariant 4-sign sequence occupies the medial spine and functions like an equals sign; a compact cluster acts as a binary addition operator; and a fixed four-sign bundle at the right edge derives “×12” forms. Complement constructions such as “11+1,” “10+2,” and “6+6” converge on the same dozen-marked targets, diagnosing 12 as the privileged base. A small number of clauses are read as scaling the same patterns to 12² and, by extension, to 12³.<ref name="Rubergskier2024" /><br />
<br />
The approach is intentionally agnostic about [[Language identification]] and about whether the glyphs are ultimately [[Logogram|logographic]], [[Syllabary|syllabic]] or something else. The claim is structural: that a small and rigid clause template—bound final punctuation, a fixed medial spine, operator clusters with narrow distribution, and a selective right-edge derivation—fits a didactic number register more parsimoniously than it fits a segmental writing system without additional evidence.<ref name="Rubergskier2024" /> Proponents note that such “equation-like” formatting is well attested in practice texts and primers across historical [[Numeral system]]s, whereas critics point out that non-linguistic genres (lists, catalogues, tallies) can sometimes mimic grammatical structure.<br />
<br />
== Glyph inventory and distribution ==<br />
<br />
A compact distribution over the transcribed sign set (Kristiansen codes) is given below. Counts refer to the Dozenal Primer Inscription as published in line drawings/transcription; code labels are descriptive only and do not imply phonetic values.<ref name="Rubergskier2024" /><ref name="Kristiansen2023h" /><br />
<br />
{| class="wikitable plainlist" style="text-align:center;"<br />
|- <br />
! scope="col" | Code<br />
! scope="col" | Glyph<br />
! scope="col" | Name<br />
! scope="col" | Freq<br />
! scope="col" | Init<br />
! scope="col" | Med<br />
! scope="col" | Final<br />
|-<br />
| A01<br />
| [[File:A01.svg|24px|alt=A01|link=]]<br />
| style="text-align:left;" | TRI-OPEN<br />
| 5 || 2 || 3 || –<br />
|-<br />
| A02<br />
| [[File:A02.svg|24px|alt=A02|link=]]<br />
| style="text-align:left;" | TRI-BAR<br />
| 17 || 17 || – || –<br />
|-<br />
| A03<br />
| [[File:A03.svg|24px|alt=A03|link=]]<br />
| style="text-align:left;" | TRI-DOT<br />
| 4 || – || 4 || –<br />
|-<br />
| A05<br />
| [[File:A05.svg|24px|alt=A05|link=]]<br />
| style="text-align:left;" | TRI-CLOSED-BAR<br />
| 3 || – || 3 || –<br />
|-<br />
| B01<br />
| [[File:B01.svg|24px|alt=B01|link=]]<br />
| style="text-align:left;" | BOX<br />
| 6 || 4 || 2 || –<br />
|-<br />
| B02<br />
| [[File:B02.svg|24px|alt=B02|link=]]<br />
| style="text-align:left;" | BOX-DOT<br />
| 5 || 5 || – || –<br />
|-<br />
| B04<br />
| [[File:B04.svg|24px|alt=B04|link=]]<br />
| style="text-align:left;" | BOX-DIAG-SW-NE<br />
| 5 || – || 3 || 2<br />
|-<br />
| C01<br />
| [[File:C01.svg|24px|alt=C01|link=]]<br />
| style="text-align:left;" | CORNER-NW<br />
| 28 || 14 || – || 14<br />
|-<br />
| C02<br />
| [[File:C02.svg|24px|alt=C02|link=]]<br />
| style="text-align:left;" | CORNER-SE<br />
| 27 || 27 || – || –<br />
|-<br />
| C03<br />
| [[File:C03.svg|24px|alt=C03|link=]]<br />
| style="text-align:left;" | CORNER-SE-DOT<br />
| 6 || 1 || 5 || –<br />
|-<br />
| C04<br />
| [[File:C04.svg|24px|alt=C04|link=]]<br />
| style="text-align:left;" | CORNER-NW-DIAG<br />
| 3 || – || 3 || –<br />
|-<br />
| C05<br />
| [[File:C05.svg|24px|alt=C05|link=]]<br />
| style="text-align:left;" | CORNER-SE-DIAG<br />
| 16 || 16 || – || –<br />
|-<br />
| C06<br />
| [[File:C06.svg|24px|alt=C06|link=]]<br />
| style="text-align:left;" | CORNER-NW-DIAG-DOT<br />
| 7 || – || 7 || –<br />
|-<br />
| H01<br />
| [[File:H01.svg|24px|alt=H01|link=]]<br />
| style="text-align:left;" | DOUBLE-POST-CONNECTED<br />
| 15 || – || 15 || –<br />
|-<br />
| H02<br />
| [[File:H02.svg|24px|alt=H02|link=]]<br />
| style="text-align:left;" | POST-DOUBLE-BAR<br />
| 8 || – || 6 || 2<br />
|-<br />
| H03<br />
| [[File:H03.svg|24px|alt=H03|link=]]<br />
| style="text-align:left;" | DOUBLE-POST-BAR<br />
| 14 || – || 14 || –<br />
|-<br />
| L01<br />
| [[File:L01.svg|24px|alt=L01|link=]]<br />
| style="text-align:left;" | LINE-VERT<br />
| 24 || – || 8 || 16<br />
|-<br />
| M01<br />
| [[File:M01.svg|24px|alt=M01|link=]]<br />
| style="text-align:left;" | COMB-2-N<br />
| 20 || 3 || 16 || 1<br />
|-<br />
| M02<br />
| [[File:M02.svg|24px|alt=M02|link=]]<br />
| style="text-align:left;" | COMB-2-W<br />
| 52 || – || 52 || –<br />
|-<br />
| M03<br />
| [[File:M03.svg|24px|alt=M03|link=]]<br />
| style="text-align:left;" | COMB-3-E<br />
| 40 || – || 40 || –<br />
|-<br />
| P01<br />
| [[File:P01.svg|24px|alt=P01|link=]]<br />
| style="text-align:left;" | SLASH<br />
| 25 || – || – || 25<br />
|-<br />
| S02<br />
| [[File:S02.svg|24px|alt=S02|link=]]<br />
| style="text-align:left;" | MEANDER-2-HOLLOW<br />
| 9 || – || 3 || 6<br />
|-<br />
| S03<br />
| [[File:S03.svg|24px|alt=S03|link=]]<br />
| style="text-align:left;" | MEANDER-3<br />
| 39 || – || 37 || 2<br />
|-<br />
| T01<br />
| [[File:T01.svg|24px|alt=T01|link=]]<br />
| style="text-align:left;" | TEE-UP<br />
| 7 || – || 4 || 3<br />
|-<br />
| T02<br />
| [[File:T02.svg|24px|alt=T02|link=]]<br />
| style="text-align:left;" | TEE-LEFT<br />
| 30 || – || 23 || 7<br />
|-<br />
| T03<br />
| [[File:T03.svg|24px|alt=T03|link=]]<br />
| style="text-align:left;" | UPSIDE-DOWN-TEE<br />
| 38 || – || 19 || 19<br />
<br />
|}<br />
<br />
<br />
== Proposed numeric forms and functional sequences ==<br />
<br />
Codes follow Kristiansen’s signary. Values are glosses for exposition only.<ref name="Rubergskier2024" />. Coding scheme per Kristiansen.<ref name="Kristiansen2023h" /><br />
<br />
{| class="wikitable plainlist" style="text-align:left;"<br />
|- <br />
! scope="col" | Function (gloss)<br />
! scope="col" | Codes (Kristiansen)<br />
! scope="col" | Glyph sequence (icons)<br />
! scope="col" | Notes<br />
|-<br />
| ZERO<br />
| <code>B02-M03-L01-B05-S03</code><br />
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:B05.svg|20px|alt=B05|link=]][[File:S03.svg|20px|alt=S03|link=]]<br />
|<br />
|-<br />
| ONE<br />
| <code>C01-S03-C03-T03</code><br />
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]<br />
|<br />
|-<br />
| TWO<br />
| <code>C02-M02-H01-M01-T01</code><br />
| [[File:C02.svg|20px|alt=C02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:T01.svg|20px|alt=T01|link=]]<br />
|<br />
|-<br />
| THREE<br />
| <code>B01-M02-T02-A03-H02</code><br />
| [[File:B01.svg|20px|alt=B01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:T02.svg|20px|alt=T02|link=]][[File:A03.svg|20px|alt=A03|link=]][[File:H02.svg|20px|alt=H02|link=]]<br />
| <br />
|-<br />
| FOUR<br />
| <code>C05-M03-S02-C06-T02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S02.svg|20px|alt=S02|link=]][[File:C06.svg|20px|alt=C06|link=]][[File:T02.svg|20px|alt=T02|link=]]<br />
| <br />
|-<br />
| FIVE<br />
| <code>C01-M03-T02</code><br />
| [[File:C01.svg|20px|alt=C01|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:T02.svg|20px|alt=T02|link=]]<br />
|<br />
|-<br />
| SIX<br />
| <code>C05-B04-L01</code><br />
| [[File:C05.svg|20px|alt=C05|link=]][[File:B04.svg|20px|alt=B04|link=]][[File:L01.svg|20px|alt=L01|link=]]<br />
|<br />
|-<br />
| SEVEN<br />
| <code>M01-L01-A01-T03</code><br />
| [[File:M01.svg|20px|alt=M01|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:A01.svg|20px|alt=A01|link=]][[File:T03.svg|20px|alt=T03|link=]]<br />
|<br />
|-<br />
| EIGHT<br />
| <code>B02-M03-S03</code><br />
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S03.svg|20px|alt=S03|link=]]<br />
|<br />
|-<br />
| NINE<br />
| <code>C05-M02-H02-A05-S02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:A05.svg|20px|alt=A05|link=]][[File:S02.svg|20px|alt=S02|link=]]<br />
|<br />
|-<br />
| TEN<br />
| <code>C05-M01-T02-M02-L01</code><br />
| [[File:C05.svg|20px|alt=C05|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:T02.svg|20px|alt=T02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:L01.svg|20px|alt=L01|link=]]<br />
|<br />
|-<br />
| ELEVEN<br />
| <code>A01-H01-B01</code><br />
| [[File:A01.svg|20px|alt=A01|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:B01.svg|20px|alt=B01|link=]]<br />
|<br />
|-<br />
| TWELVE<br />
| <code>C01-M02-H02-B04</code><br />
| [[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]<br />
|<br />
|-<br />
| '''EQUALS / clause spine'''<br />
| <code>C02–M03–H03–C01</code><br />
| [[File:C02.svg|20px|alt=C02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:H03.svg|20px|alt=H03|link=]][[File:C01.svg|20px|alt=C01|link=]]<br />
| Invariant medial sequence dividing left expression from result; reported as present in every equation clause. <ref name="Rubergskier2024" /><br />
|-<br />
| '''PLUS (binary addition)'''<br />
| <code>A02–L01</code><br />
| [[File:A02.svg|20px|alt=A02|link=]][[File:L01.svg|20px|alt=L01|link=]]<br />
| High-PMI operator cluster used in successor and complement constructions. <ref name="Rubergskier2024" /><br />
|-<br />
| '''MINUS (subtraction)'''<br />
| <code>C05–M02–S02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:S02.svg|20px|alt=S02|link=]]<br />
| Distinct collocational profile mirroring the syntax of the addition lines. <ref name="Rubergskier2024" /><br />
|-<br />
| '''ONE (simplex unit)'''<br />
| <code>C01–S03–C03–T03</code><br />
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]<br />
| Recurrent bundle functioning as the unit “one”; used to advance the successor chain. <ref name="Rubergskier2024" /><br />
|-<br />
| '''PUNCTUATION (bound period)'''<br />
| <code>P01</code> (final only)<br />
| [[File:P01.svg|20px|alt=P01|link=]]<br />
| Clause-final slash behaving as bound punctuation; not attested internally. <ref name="Rubergskier2024" /><br />
|-<br />
| '''×12 derivation (“dozen”)'''<br />
| –C01–M02–H02–B04 (right edge)<br />
| [[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]<br />
| Contiguous right-edge 4-gram treated as a derivational suffix forming multiples of twelve; composes with stems. <ref name="Rubergskier2024" /><br />
|}<br />
<br />
== Scholarly discussion ==<br />
Because the archaeological context of the longer inscription has not been publicly detailed, reception has been cautious. Supporters of the dozenal reading emphasise the conjunction of multiple independent diagnostics (final-only punctuation, a medial spine with near-zero variance, a selective right-edge four-gram, and complementary sums converging on the same target), arguing that chance alignment across all four is unlikely. Skeptics reply that without provenance, additional exemplars, or phonetic control, an arithmetic interpretation remains provisional and vulnerable to genre effects. Both sides agree on clear tests that could confirm or weaken the proposal: finding the slash P01 in non-final position; observing the putative ×12 four-gram away from clause edges; or documenting clauses that disrupt the medial spine while still behaving “arithmetically.”<ref name="Rubergskier2024" /><br />
<br />
== Nomenclature ==<br />
“Dozenal Primer Inscription” is a descriptive convenience used in secondary discussion and is not a claim about ancient self-designation. Alternative labels in circulation include “Dozenal arithmetic inscription,” “Twelve-base arithmetic inscription,” and “Kristiansen-coded arithmetic inscription.” For clarity and disambiguation within encyclopedic contexts, the present title foregrounds the proposed function (primer) and base (dozenal).<br />
<br />
== Relation to the Scapula Glyph Inscription ==<br />
The [[Scapula Glyph Inscription]] (KS-01) is much shorter but provided the stable sign labels and visual classes used in the transcription of the Dozenal Primer Inscription. KS-01 shows bipartite lines and a group-final slash divider consistent with the clause architecture proposed for the longer text, although by itself the scapula piece is too brief to display a full base-12 progression. Early notes on KS-01 also highlighted the need for direct examination and higher-quality imaging before drawing conclusions about material or chronology.<ref name="Kristiansen2023h" /><br />
<br />
== See also ==<br />
* [[Duodecimal]]<br />
* [[Numeral system]]<br />
* [[Mathematical notation]]<br />
* [[Undeciphered writing systems]]<br />
* [[Epigraphy]]<br />
* [[Paleography]]<br />
<br />
== References ==<br />
<references /></div>Mvuijlsthttps://yusupov.cloud/index.php?title=Dozenal_Primer_Inscription&diff=369Dozenal Primer Inscription2025-10-29T18:49:19Z<p>Mvuijlst: /* Proposed numeric forms and functional sequences */</p>
<hr />
<div>[[File:Dozenal successor schema.png|thumb|The four examples render the successor chain 1→2, 2→3, 3→4, 4→5, demonstrating that adding the simplex unit “ONE” advances X to its next value while preserving clause structure. Codes follow Kristiansen’s signary; glyph labels (“ONE”, “TWO”, …) are semantic glosses for expository clarity and do not assume phonetic values.]]<br />
The '''Dozenal Primer Inscription''' is the working name for a long geometric-glyph text proposed to encode a compact [[Duodecimal|dozenal]] (base-12) arithmetic register. The inscription is transcribed with a neutral code of sign classes (for example A01, B04, C03 and a slash-like divider P01) that mirrors the notation first used to document the shorter [[Scapula Glyph Inscription]] (KS-01). In 2024, a study argued from distributional evidence—rather than from phonetic values or a bilingual—that the text exhibits an equation-like clause structure with bound punctuation, a stereotyped medial “equals” spine, operator clusters, and a productive ×12 derivational suffix. On that account, the inscription functions as a brief primer for base-12 arithmetic, extending to compounds traditionally glossed as ''dozen'' (12×), ''gross'' (12²) and a tentative ''greatgross'' (12³).<ref name="Rubergskier2024">Ginevra Rubergskier, “A dozenal primer hidden in plain sight: decoding arithmetic from a corpus of tagged tokens,” ''Language Codes'' 6 (2024): 820–824.</ref><br />
<br />
The sign code used to publish the Dozenal Primer Inscription derives from earlier internal documentation of KS-01, which described short ruled lines, rectilinear glyphs built from a limited set of straight strokes, and visually coherent families (corners, boxes, triangles, barred posts) separated by a consistent slash divider. That memorandum cautioned that widely circulated images likely trace back to a single original drawing, and it advocated raking-light or RTI imaging before firm claims about medium, date or technique.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref><br />
<br />
== Overview ==<br />
The Dozenal Primer Inscription is published only as a transcription in the Kristiansen coding scheme and as line drawings; no phonetic values or language affiliation are claimed in the 2024 analysis. Instead, the argument proceeds by methods common in [[Corpus linguistics]] and quantitative [[Epigraphy]]: (1) positional bias over initial/medial/final slots; (2) bigram inventories and pointwise mutual information to find unusually tight collocations; and (3) tests for morphological productivity at the right edge of clauses. In this model, the slash P01 behaves as bound punctuation confined to clause ends; an invariant 4-sign sequence occupies the medial spine and functions like an equals sign; a compact cluster acts as a binary addition operator; and a fixed four-sign bundle at the right edge derives “×12” forms. Complement constructions such as “11+1,” “10+2,” and “6+6” converge on the same dozen-marked targets, diagnosing 12 as the privileged base. A small number of clauses are read as scaling the same patterns to 12² and, by extension, to 12³.<ref name="Rubergskier2024" /><br />
<br />
The approach is intentionally agnostic about [[Language identification]] and about whether the glyphs are ultimately [[Logogram|logographic]], [[Syllabary|syllabic]] or something else. The claim is structural: that a small and rigid clause template—bound final punctuation, a fixed medial spine, operator clusters with narrow distribution, and a selective right-edge derivation—fits a didactic number register more parsimoniously than it fits a segmental writing system without additional evidence.<ref name="Rubergskier2024" /> Proponents note that such “equation-like” formatting is well attested in practice texts and primers across historical [[Numeral system]]s, whereas critics point out that non-linguistic genres (lists, catalogues, tallies) can sometimes mimic grammatical structure.<br />
<br />
== Glyph inventory and distribution ==<br />
<br />
A compact distribution over the transcribed sign set (Kristiansen codes) is given below. Counts refer to the Dozenal Primer Inscription as published in line drawings/transcription; code labels are descriptive only and do not imply phonetic values.<ref name="Rubergskier2024" /><ref name="Kristiansen2023h" /><br />
<br />
{| class="wikitable plainlist" style="text-align:center;"<br />
|- <br />
! scope="col" | Code<br />
! scope="col" | Glyph<br />
! scope="col" | Name<br />
! scope="col" | Freq<br />
! scope="col" | Init<br />
! scope="col" | Med<br />
! scope="col" | Final<br />
|-<br />
| A01<br />
| [[File:A01.svg|24px|alt=A01|link=]]<br />
| style="text-align:left;" | TRI-OPEN<br />
| 5 || 2 || 3 || –<br />
|-<br />
| A02<br />
| [[File:A02.svg|24px|alt=A02|link=]]<br />
| style="text-align:left;" | TRI-BAR<br />
| 17 || 17 || – || –<br />
|-<br />
| A03<br />
| [[File:A03.svg|24px|alt=A03|link=]]<br />
| style="text-align:left;" | TRI-DOT<br />
| 4 || – || 4 || –<br />
|-<br />
| A05<br />
| [[File:A05.svg|24px|alt=A05|link=]]<br />
| style="text-align:left;" | TRI-CLOSED-BAR<br />
| 3 || – || 3 || –<br />
|-<br />
| B01<br />
| [[File:B01.svg|24px|alt=B01|link=]]<br />
| style="text-align:left;" | BOX<br />
| 6 || 4 || 2 || –<br />
|-<br />
| B02<br />
| [[File:B02.svg|24px|alt=B02|link=]]<br />
| style="text-align:left;" | BOX-DOT<br />
| 5 || 5 || – || –<br />
|-<br />
| B04<br />
| [[File:B04.svg|24px|alt=B04|link=]]<br />
| style="text-align:left;" | BOX-DIAG-SW-NE<br />
| 5 || – || 3 || 2<br />
|-<br />
| C01<br />
| [[File:C01.svg|24px|alt=C01|link=]]<br />
| style="text-align:left;" | CORNER-NW<br />
| 28 || 14 || – || 14<br />
|-<br />
| C02<br />
| [[File:C02.svg|24px|alt=C02|link=]]<br />
| style="text-align:left;" | CORNER-SE<br />
| 27 || 27 || – || –<br />
|-<br />
| C03<br />
| [[File:C03.svg|24px|alt=C03|link=]]<br />
| style="text-align:left;" | CORNER-SE-DOT<br />
| 6 || 1 || 5 || –<br />
|-<br />
| C04<br />
| [[File:C04.svg|24px|alt=C04|link=]]<br />
| style="text-align:left;" | CORNER-NW-DIAG<br />
| 3 || – || 3 || –<br />
|-<br />
| C05<br />
| [[File:C05.svg|24px|alt=C05|link=]]<br />
| style="text-align:left;" | CORNER-SE-DIAG<br />
| 16 || 16 || – || –<br />
|-<br />
| C06<br />
| [[File:C06.svg|24px|alt=C06|link=]]<br />
| style="text-align:left;" | CORNER-NW-DIAG-DOT<br />
| 7 || – || 7 || –<br />
|-<br />
| H01<br />
| [[File:H01.svg|24px|alt=H01|link=]]<br />
| style="text-align:left;" | DOUBLE-POST-CONNECTED<br />
| 15 || – || 15 || –<br />
|-<br />
| H02<br />
| [[File:H02.svg|24px|alt=H02|link=]]<br />
| style="text-align:left;" | POST-DOUBLE-BAR<br />
| 8 || – || 6 || 2<br />
|-<br />
| H03<br />
| [[File:H03.svg|24px|alt=H03|link=]]<br />
| style="text-align:left;" | DOUBLE-POST-BAR<br />
| 14 || – || 14 || –<br />
|-<br />
| L01<br />
| [[File:L01.svg|24px|alt=L01|link=]]<br />
| style="text-align:left;" | LINE-VERT<br />
| 24 || – || 8 || 16<br />
|-<br />
| M01<br />
| [[File:M01.svg|24px|alt=M01|link=]]<br />
| style="text-align:left;" | COMB-2-N<br />
| 20 || 3 || 16 || 1<br />
|-<br />
| M02<br />
| [[File:M02.svg|24px|alt=M02|link=]]<br />
| style="text-align:left;" | COMB-2-W<br />
| 52 || – || 52 || –<br />
|-<br />
| M03<br />
| [[File:M03.svg|24px|alt=M03|link=]]<br />
| style="text-align:left;" | COMB-3-E<br />
| 40 || – || 40 || –<br />
|-<br />
| P01<br />
| [[File:P01.svg|24px|alt=P01|link=]]<br />
| style="text-align:left;" | SLASH<br />
| 25 || – || – || 25<br />
|-<br />
| S02<br />
| [[File:S02.svg|24px|alt=S02|link=]]<br />
| style="text-align:left;" | MEANDER-2-HOLLOW<br />
| 9 || – || 3 || 6<br />
|-<br />
| S03<br />
| [[File:S03.svg|24px|alt=S03|link=]]<br />
| style="text-align:left;" | MEANDER-3<br />
| 39 || – || 37 || 2<br />
|-<br />
| T01<br />
| [[File:T01.svg|24px|alt=T01|link=]]<br />
| style="text-align:left;" | TEE-UP<br />
| 7 || – || 4 || 3<br />
|-<br />
| T02<br />
| [[File:T02.svg|24px|alt=T02|link=]]<br />
| style="text-align:left;" | TEE-LEFT<br />
| 30 || – || 23 || 7<br />
|-<br />
| T03<br />
| [[File:T03.svg|24px|alt=T03|link=]]<br />
| style="text-align:left;" | UPSIDE-DOWN-TEE<br />
| 38 || – || 19 || 19<br />
<br />
|}<br />
<br />
<br />
== Proposed numeric forms and functional sequences ==<br />
<br />
{| class="wikitable plainlist" style="text-align:left;"<br />
|- <br />
! scope="col" | Function (gloss)<br />
! scope="col" | Codes (Kristiansen)<br />
! scope="col" | Glyph sequence (icons)<br />
! scope="col" | Notes<br />
|-<br />
| ZERO<br />
| <code>B02-M03-L01-B05-S03</code><br />
| [[File:B02.svg|20px|alt=B02|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:L01.svg|20px|alt=L01|link=]] [[File:B05.svg|20px|alt=B05|link=]] [[File:S03.svg|20px|alt=S03|link=]]<br />
|<br />
|-<br />
| ONE<br />
| <code>C01-S03-C03-T03</code><br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:S03.svg|20px|alt=S03|link=]] [[File:C03.svg|20px|alt=C03|link=]] [[File:T03.svg|20px|alt=T03|link=]]<br />
|<br />
|-<br />
| TWO<br />
| <code>C02-M02-H01-M01-T01</code><br />
| [[File:C02.svg|20px|alt=C02|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H01.svg|20px|alt=H01|link=]] [[File:M01.svg|20px|alt=M01|link=]] [[File:T01.svg|20px|alt=T01|link=]]<br />
|<br />
|-<br />
| THREE<br />
| <code>B01-M02-T02-A03-H02</code><br />
| [[File:B01.svg|20px|alt=B01|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:T02.svg|20px|alt=T02|link=]] [[File:A03.svg|20px|alt=A03|link=]] [[File:H02.svg|20px|alt=H02|link=]]<br />
| <br />
|-<br />
| FOUR<br />
| <code>C05-M03-S02-C06-T02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:S02.svg|20px|alt=S02|link=]] [[File:C06.svg|20px|alt=C06|link=]] [[File:T02.svg|20px|alt=T02|link=]]<br />
| <br />
|-<br />
| FIVE<br />
| <code>C01-M03-T02</code><br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:T02.svg|20px|alt=T02|link=]]<br />
|<br />
|-<br />
| SIX<br />
| <code>C05-B04-L01</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:B04.svg|20px|alt=B04|link=]] [[File:L01.svg|20px|alt=L01|link=]]<br />
|<br />
|-<br />
| SEVEN<br />
| <code>M01-L01-A01-T03</code><br />
| [[File:M01.svg|20px|alt=M01|link=]] [[File:L01.svg|20px|alt=L01|link=]] [[File:A01.svg|20px|alt=A01|link=]] [[File:T03.svg|20px|alt=T03|link=]]<br />
|<br />
|-<br />
| EIGHT<br />
| <code>B02-M03-S03</code><br />
| [[File:B02.svg|20px|alt=B02|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:S03.svg|20px|alt=S03|link=]]<br />
|<br />
|-<br />
| NINE<br />
| <code>C05-M02-H02-A05-S02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H02.svg|20px|alt=H02|link=]] [[File:A05.svg|20px|alt=A05|link=]] [[File:S02.svg|20px|alt=S02|link=]]<br />
|<br />
|-<br />
| TEN<br />
| <code>C05-M01-T02-M02-L01</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M01.svg|20px|alt=M01|link=]] [[File:T02.svg|20px|alt=T02|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:L01.svg|20px|alt=L01|link=]]<br />
|<br />
|-<br />
| ELEVEN<br />
| <code>A01-H01-B01</code><br />
| [[File:A01.svg|20px|alt=A01|link=]] [[File:H01.svg|20px|alt=H01|link=]] [[File:B01.svg|20px|alt=B01|link=]]<br />
|<br />
|-<br />
| TWELVE<br />
| <code>C01-M02-H02-B04</code><br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H02.svg|20px|alt=H02|link=]] [[File:B04.svg|20px|alt=B04|link=]]<br />
|<br />
|-<br />
| '''EQUALS / clause spine'''<br />
| <code>C02–M03–H03–C01</code><br />
| [[File:C02.svg|20px|alt=C02|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:H03.svg|20px|alt=H03|link=]] [[File:C01.svg|20px|alt=C01|link=]]<br />
| Invariant medial sequence dividing left expression from result; reported as present in every equation clause. <ref name="Rubergskier2024" /><br />
|-<br />
| '''PLUS (binary addition)'''<br />
| <code>A02–L01</code><br />
| [[File:A02.svg|20px|alt=A02|link=]] [[File:L01.svg|20px|alt=L01|link=]]<br />
| High-PMI operator cluster used in successor and complement constructions. <ref name="Rubergskier2024" /><br />
|-<br />
| '''MINUS (subtraction)'''<br />
| <code>C05–M02–S02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:S02.svg|20px|alt=S02|link=]]<br />
| Distinct collocational profile mirroring the syntax of the addition lines. <ref name="Rubergskier2024" /><br />
|-<br />
| '''ONE (simplex unit)'''<br />
| <code>C01–S03–C03–T03</code><br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:S03.svg|20px|alt=S03|link=]] [[File:C03.svg|20px|alt=C03|link=]] [[File:T03.svg|20px|alt=T03|link=]]<br />
| Recurrent bundle functioning as the unit “one”; used to advance the successor chain. <ref name="Rubergskier2024" /><br />
|-<br />
| '''PUNCTUATION (bound period)'''<br />
| <code>P01</code> (final only)<br />
| [[File:P01.svg|20px|alt=P01|link=]]<br />
| Clause-final slash behaving as bound punctuation; not attested internally. <ref name="Rubergskier2024" /><br />
|-<br />
| '''×12 derivation (“dozen”)'''<br />
| –C01–M02–H02–B04 (right edge)<br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H02.svg|20px|alt=H02|link=]] [[File:B04.svg|20px|alt=B04|link=]]<br />
| Contiguous right-edge 4-gram treated as a derivational suffix forming multiples of twelve; composes with stems. <ref name="Rubergskier2024" /><br />
|}<br />
<br />
== Scholarly discussion ==<br />
Because the archaeological context of the longer inscription has not been publicly detailed, reception has been cautious. Supporters of the dozenal reading emphasise the conjunction of multiple independent diagnostics (final-only punctuation, a medial spine with near-zero variance, a selective right-edge four-gram, and complementary sums converging on the same target), arguing that chance alignment across all four is unlikely. Skeptics reply that without provenance, additional exemplars, or phonetic control, an arithmetic interpretation remains provisional and vulnerable to genre effects. Both sides agree on clear tests that could confirm or weaken the proposal: finding the slash P01 in non-final position; observing the putative ×12 four-gram away from clause edges; or documenting clauses that disrupt the medial spine while still behaving “arithmetically.”<ref name="Rubergskier2024" /><br />
<br />
== Nomenclature ==<br />
“Dozenal Primer Inscription” is a descriptive convenience used in secondary discussion and is not a claim about ancient self-designation. Alternative labels in circulation include “Dozenal arithmetic inscription,” “Twelve-base arithmetic inscription,” and “Kristiansen-coded arithmetic inscription.” For clarity and disambiguation within encyclopedic contexts, the present title foregrounds the proposed function (primer) and base (dozenal).<br />
<br />
== Relation to the Scapula Glyph Inscription ==<br />
The [[Scapula Glyph Inscription]] (KS-01) is much shorter but provided the stable sign labels and visual classes used in the transcription of the Dozenal Primer Inscription. KS-01 shows bipartite lines and a group-final slash divider consistent with the clause architecture proposed for the longer text, although by itself the scapula piece is too brief to display a full base-12 progression. Early notes on KS-01 also highlighted the need for direct examination and higher-quality imaging before drawing conclusions about material or chronology.<ref name="Kristiansen2023h" /><br />
<br />
== See also ==<br />
* [[Duodecimal]]<br />
* [[Numeral system]]<br />
* [[Mathematical notation]]<br />
* [[Undeciphered writing systems]]<br />
* [[Epigraphy]]<br />
* [[Paleography]]<br />
<br />
== References ==<br />
<references /></div>Mvuijlsthttps://yusupov.cloud/index.php?title=Dozenal_Primer_Inscription&diff=368Dozenal Primer Inscription2025-10-29T18:48:00Z<p>Mvuijlst: /* Proposed numeric forms and functional sequences */</p>
<hr />
<div>[[File:Dozenal successor schema.png|thumb|The four examples render the successor chain 1→2, 2→3, 3→4, 4→5, demonstrating that adding the simplex unit “ONE” advances X to its next value while preserving clause structure. Codes follow Kristiansen’s signary; glyph labels (“ONE”, “TWO”, …) are semantic glosses for expository clarity and do not assume phonetic values.]]<br />
The '''Dozenal Primer Inscription''' is the working name for a long geometric-glyph text proposed to encode a compact [[Duodecimal|dozenal]] (base-12) arithmetic register. The inscription is transcribed with a neutral code of sign classes (for example A01, B04, C03 and a slash-like divider P01) that mirrors the notation first used to document the shorter [[Scapula Glyph Inscription]] (KS-01). In 2024, a study argued from distributional evidence—rather than from phonetic values or a bilingual—that the text exhibits an equation-like clause structure with bound punctuation, a stereotyped medial “equals” spine, operator clusters, and a productive ×12 derivational suffix. On that account, the inscription functions as a brief primer for base-12 arithmetic, extending to compounds traditionally glossed as ''dozen'' (12×), ''gross'' (12²) and a tentative ''greatgross'' (12³).<ref name="Rubergskier2024">Ginevra Rubergskier, “A dozenal primer hidden in plain sight: decoding arithmetic from a corpus of tagged tokens,” ''Language Codes'' 6 (2024): 820–824.</ref><br />
<br />
The sign code used to publish the Dozenal Primer Inscription derives from earlier internal documentation of KS-01, which described short ruled lines, rectilinear glyphs built from a limited set of straight strokes, and visually coherent families (corners, boxes, triangles, barred posts) separated by a consistent slash divider. That memorandum cautioned that widely circulated images likely trace back to a single original drawing, and it advocated raking-light or RTI imaging before firm claims about medium, date or technique.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref><br />
<br />
== Overview ==<br />
The Dozenal Primer Inscription is published only as a transcription in the Kristiansen coding scheme and as line drawings; no phonetic values or language affiliation are claimed in the 2024 analysis. Instead, the argument proceeds by methods common in [[Corpus linguistics]] and quantitative [[Epigraphy]]: (1) positional bias over initial/medial/final slots; (2) bigram inventories and pointwise mutual information to find unusually tight collocations; and (3) tests for morphological productivity at the right edge of clauses. In this model, the slash P01 behaves as bound punctuation confined to clause ends; an invariant 4-sign sequence occupies the medial spine and functions like an equals sign; a compact cluster acts as a binary addition operator; and a fixed four-sign bundle at the right edge derives “×12” forms. Complement constructions such as “11+1,” “10+2,” and “6+6” converge on the same dozen-marked targets, diagnosing 12 as the privileged base. A small number of clauses are read as scaling the same patterns to 12² and, by extension, to 12³.<ref name="Rubergskier2024" /><br />
<br />
The approach is intentionally agnostic about [[Language identification]] and about whether the glyphs are ultimately [[Logogram|logographic]], [[Syllabary|syllabic]] or something else. The claim is structural: that a small and rigid clause template—bound final punctuation, a fixed medial spine, operator clusters with narrow distribution, and a selective right-edge derivation—fits a didactic number register more parsimoniously than it fits a segmental writing system without additional evidence.<ref name="Rubergskier2024" /> Proponents note that such “equation-like” formatting is well attested in practice texts and primers across historical [[Numeral system]]s, whereas critics point out that non-linguistic genres (lists, catalogues, tallies) can sometimes mimic grammatical structure.<br />
<br />
== Glyph inventory and distribution ==<br />
<br />
A compact distribution over the transcribed sign set (Kristiansen codes) is given below. Counts refer to the Dozenal Primer Inscription as published in line drawings/transcription; code labels are descriptive only and do not imply phonetic values.<ref name="Rubergskier2024" /><ref name="Kristiansen2023h" /><br />
<br />
{| class="wikitable plainlist" style="text-align:center;"<br />
|- <br />
! scope="col" | Code<br />
! scope="col" | Glyph<br />
! scope="col" | Name<br />
! scope="col" | Freq<br />
! scope="col" | Init<br />
! scope="col" | Med<br />
! scope="col" | Final<br />
|-<br />
| A01<br />
| [[File:A01.svg|24px|alt=A01|link=]]<br />
| style="text-align:left;" | TRI-OPEN<br />
| 5 || 2 || 3 || –<br />
|-<br />
| A02<br />
| [[File:A02.svg|24px|alt=A02|link=]]<br />
| style="text-align:left;" | TRI-BAR<br />
| 17 || 17 || – || –<br />
|-<br />
| A03<br />
| [[File:A03.svg|24px|alt=A03|link=]]<br />
| style="text-align:left;" | TRI-DOT<br />
| 4 || – || 4 || –<br />
|-<br />
| A05<br />
| [[File:A05.svg|24px|alt=A05|link=]]<br />
| style="text-align:left;" | TRI-CLOSED-BAR<br />
| 3 || – || 3 || –<br />
|-<br />
| B01<br />
| [[File:B01.svg|24px|alt=B01|link=]]<br />
| style="text-align:left;" | BOX<br />
| 6 || 4 || 2 || –<br />
|-<br />
| B02<br />
| [[File:B02.svg|24px|alt=B02|link=]]<br />
| style="text-align:left;" | BOX-DOT<br />
| 5 || 5 || – || –<br />
|-<br />
| B04<br />
| [[File:B04.svg|24px|alt=B04|link=]]<br />
| style="text-align:left;" | BOX-DIAG-SW-NE<br />
| 5 || – || 3 || 2<br />
|-<br />
| C01<br />
| [[File:C01.svg|24px|alt=C01|link=]]<br />
| style="text-align:left;" | CORNER-NW<br />
| 28 || 14 || – || 14<br />
|-<br />
| C02<br />
| [[File:C02.svg|24px|alt=C02|link=]]<br />
| style="text-align:left;" | CORNER-SE<br />
| 27 || 27 || – || –<br />
|-<br />
| C03<br />
| [[File:C03.svg|24px|alt=C03|link=]]<br />
| style="text-align:left;" | CORNER-SE-DOT<br />
| 6 || 1 || 5 || –<br />
|-<br />
| C04<br />
| [[File:C04.svg|24px|alt=C04|link=]]<br />
| style="text-align:left;" | CORNER-NW-DIAG<br />
| 3 || – || 3 || –<br />
|-<br />
| C05<br />
| [[File:C05.svg|24px|alt=C05|link=]]<br />
| style="text-align:left;" | CORNER-SE-DIAG<br />
| 16 || 16 || – || –<br />
|-<br />
| C06<br />
| [[File:C06.svg|24px|alt=C06|link=]]<br />
| style="text-align:left;" | CORNER-NW-DIAG-DOT<br />
| 7 || – || 7 || –<br />
|-<br />
| H01<br />
| [[File:H01.svg|24px|alt=H01|link=]]<br />
| style="text-align:left;" | DOUBLE-POST-CONNECTED<br />
| 15 || – || 15 || –<br />
|-<br />
| H02<br />
| [[File:H02.svg|24px|alt=H02|link=]]<br />
| style="text-align:left;" | POST-DOUBLE-BAR<br />
| 8 || – || 6 || 2<br />
|-<br />
| H03<br />
| [[File:H03.svg|24px|alt=H03|link=]]<br />
| style="text-align:left;" | DOUBLE-POST-BAR<br />
| 14 || – || 14 || –<br />
|-<br />
| L01<br />
| [[File:L01.svg|24px|alt=L01|link=]]<br />
| style="text-align:left;" | LINE-VERT<br />
| 24 || – || 8 || 16<br />
|-<br />
| M01<br />
| [[File:M01.svg|24px|alt=M01|link=]]<br />
| style="text-align:left;" | COMB-2-N<br />
| 20 || 3 || 16 || 1<br />
|-<br />
| M02<br />
| [[File:M02.svg|24px|alt=M02|link=]]<br />
| style="text-align:left;" | COMB-2-W<br />
| 52 || – || 52 || –<br />
|-<br />
| M03<br />
| [[File:M03.svg|24px|alt=M03|link=]]<br />
| style="text-align:left;" | COMB-3-E<br />
| 40 || – || 40 || –<br />
|-<br />
| P01<br />
| [[File:P01.svg|24px|alt=P01|link=]]<br />
| style="text-align:left;" | SLASH<br />
| 25 || – || – || 25<br />
|-<br />
| S02<br />
| [[File:S02.svg|24px|alt=S02|link=]]<br />
| style="text-align:left;" | MEANDER-2-HOLLOW<br />
| 9 || – || 3 || 6<br />
|-<br />
| S03<br />
| [[File:S03.svg|24px|alt=S03|link=]]<br />
| style="text-align:left;" | MEANDER-3<br />
| 39 || – || 37 || 2<br />
|-<br />
| T01<br />
| [[File:T01.svg|24px|alt=T01|link=]]<br />
| style="text-align:left;" | TEE-UP<br />
| 7 || – || 4 || 3<br />
|-<br />
| T02<br />
| [[File:T02.svg|24px|alt=T02|link=]]<br />
| style="text-align:left;" | TEE-LEFT<br />
| 30 || – || 23 || 7<br />
|-<br />
| T03<br />
| [[File:T03.svg|24px|alt=T03|link=]]<br />
| style="text-align:left;" | UPSIDE-DOWN-TEE<br />
| 38 || – || 19 || 19<br />
<br />
|}<br />
<br />
<br />
== Proposed numeric forms and functional sequences ==<br />
<br />
{| class="wikitable plainlist" style="text-align:left;"<br />
|- <br />
! scope="col" | Function (gloss)<br />
! scope="col" | Codes (Kristiansen)<br />
! scope="col" | Glyph sequence (icons)<br />
! scope="col" | Notes<br />
|-<br />
| ZERO<br />
| <code>B02-M03-L01-B05-S03</code><br />
| [[File:B02.svg|20px|alt=B02|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:L01.svg|20px|alt=L01|link=]] [[File:B05.svg|20px|alt=B05|link=]] [[File:S03.svg|20px|alt=S03|link=]]<br />
|<br />
|-<br />
| ONE<br />
| <code>C01-S03-C03-T03</code><br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:S03.svg|20px|alt=S03|link=]] [[File:C03.svg|20px|alt=C03|link=]] [[File:T03.svg|20px|alt=T03|link=]]<br />
|<br />
|-<br />
| TWO<br />
| <code>C02-M02-H01-M01-T01</code><br />
| [[File:C02.svg|20px|alt=C02|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H01.svg|20px|alt=H01|link=]] [[File:M01.svg|20px|alt=M01|link=]] [[File:T01.svg|20px|alt=T01|link=]]<br />
|<br />
|-<br />
| THREE<br />
| <code>B01-M02-T02-A03-H02</code><br />
| [[File:B01.svg|20px|alt=B01|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:T02.svg|20px|alt=T02|link=]] [[File:A03.svg|20px|alt=A03|link=]] [[File:H02.svg|20px|alt=H02|link=]]<br />
| <br />
|-<br />
| FOUR<br />
| <code>C05-M03-S02-C06-T02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:S02.svg|20px|alt=S02|link=]] [[File:C06.svg|20px|alt=C06|link=]] [[File:T02.svg|20px|alt=T02|link=]]<br />
| <br />
|-<br />
| FIVE<br />
| <code>C01-M03-T02</code><br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:T02.svg|20px|alt=T02|link=]]<br />
|<br />
|-<br />
| SIX<br />
| <code>C05-B04-L01</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:B04.svg|20px|alt=B04|link=]] [[File:L01.svg|20px|alt=L01|link=]]<br />
|<br />
|-<br />
| SEVEN<br />
| <code>M01-L01-A01-T03</code><br />
| [[File:M01.svg|20px|alt=M01|link=]] [[File:L01.svg|20px|alt=L01|link=]] [[File:A01.svg|20px|alt=A01|link=]] [[File:T03.svg|20px|alt=T03|link=]]<br />
|<br />
|-<br />
| EIGHT<br />
| <code>B02-M03-S03</code><br />
| [[File:B02.svg|20px|alt=B02|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:S03.svg|20px|alt=S03|link=]]<br />
|<br />
|-<br />
| NINE<br />
| <code>C05-M02-H02-A05-S02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H02.svg|20px|alt=H02|link=]] [[File:A05.svg|20px|alt=A05|link=]] [[File:S02.svg|20px|alt=S02|link=]]<br />
|<br />
|-<br />
| TEN<br />
| <code>C05-M01-T02-M02-L01</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M01.svg|20px|alt=M01|link=]] [[File:T02.svg|20px|alt=T02|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:L01.svg|20px|alt=L01|link=]]<br />
|<br />
|-<br />
| ELEVEN<br />
| <code>A01-H01-B01</code><br />
| [[File:A01.svg|20px|alt=A01|link=]] [[File:H01.svg|20px|alt=H01|link=]] [[File:B01.svg|20px|alt=B01|link=]]<br />
|<br />
|-<br />
| TWELVE<br />
| <code>C01-M02-H02-B04</code><br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H02.svg|20px|alt=H02|link=]] [[File:B04.svg|20px|alt=B04|link=]]<br />
|<br />
|-<br />
| '''EQUALS / clause spine'''<br />
| C02–M03–H03–C01<br />
| [[File:C02.svg|20px|alt=C02|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:H03.svg|20px|alt=H03|link=]] [[File:C01.svg|20px|alt=C01|link=]]<br />
| Invariant medial sequence dividing left expression from result; reported as present in every equation clause. <ref name="Rubergskier2024" /><br />
|-<br />
| '''PLUS (binary addition)'''<br />
| A02–L01<br />
| [[File:A02.svg|20px|alt=A02|link=]] [[File:L01.svg|20px|alt=L01|link=]]<br />
| High-PMI operator cluster used in successor and complement constructions. <ref name="Rubergskier2024" /><br />
|-<br />
| '''MINUS (subtraction)'''<br />
| C05–M02–S02<br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:S02.svg|20px|alt=S02|link=]]<br />
| Distinct collocational profile mirroring the syntax of the addition lines. <ref name="Rubergskier2024" /><br />
|-<br />
| '''ONE (simplex unit)'''<br />
| C01–S03–C03–T03<br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:S03.svg|20px|alt=S03|link=]] [[File:C03.svg|20px|alt=C03|link=]] [[File:T03.svg|20px|alt=T03|link=]]<br />
| Recurrent bundle functioning as the unit “one”; used to advance the successor chain. <ref name="Rubergskier2024" /><br />
|-<br />
| '''PUNCTUATION (bound period)'''<br />
| P01 (final only)<br />
| [[File:P01.svg|20px|alt=P01|link=]]<br />
| Clause-final slash behaving as bound punctuation; not attested internally. <ref name="Rubergskier2024" /><br />
|-<br />
| '''×12 derivation (“dozen”)'''<br />
| –C01–M02–H02–B04 (right edge)<br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H02.svg|20px|alt=H02|link=]] [[File:B04.svg|20px|alt=B04|link=]]<br />
| Contiguous right-edge 4-gram treated as a derivational suffix forming multiples of twelve; composes with stems. <ref name="Rubergskier2024" /><br />
|}<br />
<br />
== Scholarly discussion ==<br />
Because the archaeological context of the longer inscription has not been publicly detailed, reception has been cautious. Supporters of the dozenal reading emphasise the conjunction of multiple independent diagnostics (final-only punctuation, a medial spine with near-zero variance, a selective right-edge four-gram, and complementary sums converging on the same target), arguing that chance alignment across all four is unlikely. Skeptics reply that without provenance, additional exemplars, or phonetic control, an arithmetic interpretation remains provisional and vulnerable to genre effects. Both sides agree on clear tests that could confirm or weaken the proposal: finding the slash P01 in non-final position; observing the putative ×12 four-gram away from clause edges; or documenting clauses that disrupt the medial spine while still behaving “arithmetically.”<ref name="Rubergskier2024" /><br />
<br />
== Nomenclature ==<br />
“Dozenal Primer Inscription” is a descriptive convenience used in secondary discussion and is not a claim about ancient self-designation. Alternative labels in circulation include “Dozenal arithmetic inscription,” “Twelve-base arithmetic inscription,” and “Kristiansen-coded arithmetic inscription.” For clarity and disambiguation within encyclopedic contexts, the present title foregrounds the proposed function (primer) and base (dozenal).<br />
<br />
== Relation to the Scapula Glyph Inscription ==<br />
The [[Scapula Glyph Inscription]] (KS-01) is much shorter but provided the stable sign labels and visual classes used in the transcription of the Dozenal Primer Inscription. KS-01 shows bipartite lines and a group-final slash divider consistent with the clause architecture proposed for the longer text, although by itself the scapula piece is too brief to display a full base-12 progression. Early notes on KS-01 also highlighted the need for direct examination and higher-quality imaging before drawing conclusions about material or chronology.<ref name="Kristiansen2023h" /><br />
<br />
== See also ==<br />
* [[Duodecimal]]<br />
* [[Numeral system]]<br />
* [[Mathematical notation]]<br />
* [[Undeciphered writing systems]]<br />
* [[Epigraphy]]<br />
* [[Paleography]]<br />
<br />
== References ==<br />
<references /></div>Mvuijlsthttps://yusupov.cloud/index.php?title=Dozenal_Primer_Inscription&diff=367Dozenal Primer Inscription2025-10-29T18:47:36Z<p>Mvuijlst: /* Proposed numeric forms and functional sequences */</p>
<hr />
<div>[[File:Dozenal successor schema.png|thumb|The four examples render the successor chain 1→2, 2→3, 3→4, 4→5, demonstrating that adding the simplex unit “ONE” advances X to its next value while preserving clause structure. Codes follow Kristiansen’s signary; glyph labels (“ONE”, “TWO”, …) are semantic glosses for expository clarity and do not assume phonetic values.]]<br />
The '''Dozenal Primer Inscription''' is the working name for a long geometric-glyph text proposed to encode a compact [[Duodecimal|dozenal]] (base-12) arithmetic register. The inscription is transcribed with a neutral code of sign classes (for example A01, B04, C03 and a slash-like divider P01) that mirrors the notation first used to document the shorter [[Scapula Glyph Inscription]] (KS-01). In 2024, a study argued from distributional evidence—rather than from phonetic values or a bilingual—that the text exhibits an equation-like clause structure with bound punctuation, a stereotyped medial “equals” spine, operator clusters, and a productive ×12 derivational suffix. On that account, the inscription functions as a brief primer for base-12 arithmetic, extending to compounds traditionally glossed as ''dozen'' (12×), ''gross'' (12²) and a tentative ''greatgross'' (12³).<ref name="Rubergskier2024">Ginevra Rubergskier, “A dozenal primer hidden in plain sight: decoding arithmetic from a corpus of tagged tokens,” ''Language Codes'' 6 (2024): 820–824.</ref><br />
<br />
The sign code used to publish the Dozenal Primer Inscription derives from earlier internal documentation of KS-01, which described short ruled lines, rectilinear glyphs built from a limited set of straight strokes, and visually coherent families (corners, boxes, triangles, barred posts) separated by a consistent slash divider. That memorandum cautioned that widely circulated images likely trace back to a single original drawing, and it advocated raking-light or RTI imaging before firm claims about medium, date or technique.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref><br />
<br />
== Overview ==<br />
The Dozenal Primer Inscription is published only as a transcription in the Kristiansen coding scheme and as line drawings; no phonetic values or language affiliation are claimed in the 2024 analysis. Instead, the argument proceeds by methods common in [[Corpus linguistics]] and quantitative [[Epigraphy]]: (1) positional bias over initial/medial/final slots; (2) bigram inventories and pointwise mutual information to find unusually tight collocations; and (3) tests for morphological productivity at the right edge of clauses. In this model, the slash P01 behaves as bound punctuation confined to clause ends; an invariant 4-sign sequence occupies the medial spine and functions like an equals sign; a compact cluster acts as a binary addition operator; and a fixed four-sign bundle at the right edge derives “×12” forms. Complement constructions such as “11+1,” “10+2,” and “6+6” converge on the same dozen-marked targets, diagnosing 12 as the privileged base. A small number of clauses are read as scaling the same patterns to 12² and, by extension, to 12³.<ref name="Rubergskier2024" /><br />
<br />
The approach is intentionally agnostic about [[Language identification]] and about whether the glyphs are ultimately [[Logogram|logographic]], [[Syllabary|syllabic]] or something else. The claim is structural: that a small and rigid clause template—bound final punctuation, a fixed medial spine, operator clusters with narrow distribution, and a selective right-edge derivation—fits a didactic number register more parsimoniously than it fits a segmental writing system without additional evidence.<ref name="Rubergskier2024" /> Proponents note that such “equation-like” formatting is well attested in practice texts and primers across historical [[Numeral system]]s, whereas critics point out that non-linguistic genres (lists, catalogues, tallies) can sometimes mimic grammatical structure.<br />
<br />
== Glyph inventory and distribution ==<br />
<br />
A compact distribution over the transcribed sign set (Kristiansen codes) is given below. Counts refer to the Dozenal Primer Inscription as published in line drawings/transcription; code labels are descriptive only and do not imply phonetic values.<ref name="Rubergskier2024" /><ref name="Kristiansen2023h" /><br />
<br />
{| class="wikitable plainlist" style="text-align:center;"<br />
|- <br />
! scope="col" | Code<br />
! scope="col" | Glyph<br />
! scope="col" | Name<br />
! scope="col" | Freq<br />
! scope="col" | Init<br />
! scope="col" | Med<br />
! scope="col" | Final<br />
|-<br />
| A01<br />
| [[File:A01.svg|24px|alt=A01|link=]]<br />
| style="text-align:left;" | TRI-OPEN<br />
| 5 || 2 || 3 || –<br />
|-<br />
| A02<br />
| [[File:A02.svg|24px|alt=A02|link=]]<br />
| style="text-align:left;" | TRI-BAR<br />
| 17 || 17 || – || –<br />
|-<br />
| A03<br />
| [[File:A03.svg|24px|alt=A03|link=]]<br />
| style="text-align:left;" | TRI-DOT<br />
| 4 || – || 4 || –<br />
|-<br />
| A05<br />
| [[File:A05.svg|24px|alt=A05|link=]]<br />
| style="text-align:left;" | TRI-CLOSED-BAR<br />
| 3 || – || 3 || –<br />
|-<br />
| B01<br />
| [[File:B01.svg|24px|alt=B01|link=]]<br />
| style="text-align:left;" | BOX<br />
| 6 || 4 || 2 || –<br />
|-<br />
| B02<br />
| [[File:B02.svg|24px|alt=B02|link=]]<br />
| style="text-align:left;" | BOX-DOT<br />
| 5 || 5 || – || –<br />
|-<br />
| B04<br />
| [[File:B04.svg|24px|alt=B04|link=]]<br />
| style="text-align:left;" | BOX-DIAG-SW-NE<br />
| 5 || – || 3 || 2<br />
|-<br />
| C01<br />
| [[File:C01.svg|24px|alt=C01|link=]]<br />
| style="text-align:left;" | CORNER-NW<br />
| 28 || 14 || – || 14<br />
|-<br />
| C02<br />
| [[File:C02.svg|24px|alt=C02|link=]]<br />
| style="text-align:left;" | CORNER-SE<br />
| 27 || 27 || – || –<br />
|-<br />
| C03<br />
| [[File:C03.svg|24px|alt=C03|link=]]<br />
| style="text-align:left;" | CORNER-SE-DOT<br />
| 6 || 1 || 5 || –<br />
|-<br />
| C04<br />
| [[File:C04.svg|24px|alt=C04|link=]]<br />
| style="text-align:left;" | CORNER-NW-DIAG<br />
| 3 || – || 3 || –<br />
|-<br />
| C05<br />
| [[File:C05.svg|24px|alt=C05|link=]]<br />
| style="text-align:left;" | CORNER-SE-DIAG<br />
| 16 || 16 || – || –<br />
|-<br />
| C06<br />
| [[File:C06.svg|24px|alt=C06|link=]]<br />
| style="text-align:left;" | CORNER-NW-DIAG-DOT<br />
| 7 || – || 7 || –<br />
|-<br />
| H01<br />
| [[File:H01.svg|24px|alt=H01|link=]]<br />
| style="text-align:left;" | DOUBLE-POST-CONNECTED<br />
| 15 || – || 15 || –<br />
|-<br />
| H02<br />
| [[File:H02.svg|24px|alt=H02|link=]]<br />
| style="text-align:left;" | POST-DOUBLE-BAR<br />
| 8 || – || 6 || 2<br />
|-<br />
| H03<br />
| [[File:H03.svg|24px|alt=H03|link=]]<br />
| style="text-align:left;" | DOUBLE-POST-BAR<br />
| 14 || – || 14 || –<br />
|-<br />
| L01<br />
| [[File:L01.svg|24px|alt=L01|link=]]<br />
| style="text-align:left;" | LINE-VERT<br />
| 24 || – || 8 || 16<br />
|-<br />
| M01<br />
| [[File:M01.svg|24px|alt=M01|link=]]<br />
| style="text-align:left;" | COMB-2-N<br />
| 20 || 3 || 16 || 1<br />
|-<br />
| M02<br />
| [[File:M02.svg|24px|alt=M02|link=]]<br />
| style="text-align:left;" | COMB-2-W<br />
| 52 || – || 52 || –<br />
|-<br />
| M03<br />
| [[File:M03.svg|24px|alt=M03|link=]]<br />
| style="text-align:left;" | COMB-3-E<br />
| 40 || – || 40 || –<br />
|-<br />
| P01<br />
| [[File:P01.svg|24px|alt=P01|link=]]<br />
| style="text-align:left;" | SLASH<br />
| 25 || – || – || 25<br />
|-<br />
| S02<br />
| [[File:S02.svg|24px|alt=S02|link=]]<br />
| style="text-align:left;" | MEANDER-2-HOLLOW<br />
| 9 || – || 3 || 6<br />
|-<br />
| S03<br />
| [[File:S03.svg|24px|alt=S03|link=]]<br />
| style="text-align:left;" | MEANDER-3<br />
| 39 || – || 37 || 2<br />
|-<br />
| T01<br />
| [[File:T01.svg|24px|alt=T01|link=]]<br />
| style="text-align:left;" | TEE-UP<br />
| 7 || – || 4 || 3<br />
|-<br />
| T02<br />
| [[File:T02.svg|24px|alt=T02|link=]]<br />
| style="text-align:left;" | TEE-LEFT<br />
| 30 || – || 23 || 7<br />
|-<br />
| T03<br />
| [[File:T03.svg|24px|alt=T03|link=]]<br />
| style="text-align:left;" | UPSIDE-DOWN-TEE<br />
| 38 || – || 19 || 19<br />
<br />
|}<br />
<br />
<br />
== Proposed numeric forms and functional sequences ==<br />
<br />
{| class="wikitable plainlist" style="text-align:left;"<br />
|- <br />
! scope="col" | Function (gloss)<br />
! scope="col" | Codes (Kristiansen)<br />
! scope="col" | Glyph sequence (icons)<br />
! scope="col" | Notes<br />
|-<br />
| ZERO<br />
| <code>B02-M03-L01-B05-S03</code><br />
| [[File:B02.svg|20px|alt=B02|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:L01.svg|20px|alt=L01|link=]] [[File:B05.svg|20px|alt=B05|link=]] [[File:S03.svg|20px|alt=S03|link=]]<br />
|<br />
|-<br />
| ONE<br />
| <code>C01-S03-C03-T03</code><br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:S03.svg|20px|alt=S03|link=]] [[File:C03.svg|20px|alt=C03|link=]] [[File:T03.svg|20px|alt=T03|link=]]<br />
|<br />
|-<br />
| TWO<br />
| <code>C02-M02-H01-M01-T01</code><br />
| [[File:C02.svg|20px|alt=C02|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H01.svg|20px|alt=H01|link=]] [[File:M01.svg|20px|alt=M01|link=]] [[File:T01.svg|20px|alt=T01|link=]]<br />
|<br />
|-<br />
| THREE<br />
| <code>B01-M02-T02-A03-H02</code><br />
| [[File:B01.svg|20px|alt=B01|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:T02.svg|20px|alt=T02|link=]] [[File:A03.svg|20px|alt=A03|link=]] [[File:H02.svg|20px|alt=H02|link=]]<br />
| dd<br />
-<br />
| FOUR<br />
| <code>C05-M03-S02-C06-T02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:S02.svg|20px|alt=S02|link=]] [[File:C06.svg|20px|alt=C06|link=]] [[File:T02.svg|20px|alt=T02|link=]]<br />
|<br />
|-<br />
| FIVE<br />
| <code>C01-M03-T02</code><br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:T02.svg|20px|alt=T02|link=]]<br />
|<br />
|-<br />
| SIX<br />
| <code>C05-B04-L01</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:B04.svg|20px|alt=B04|link=]] [[File:L01.svg|20px|alt=L01|link=]]<br />
|<br />
|-<br />
| SEVEN<br />
| <code>M01-L01-A01-T03</code><br />
| [[File:M01.svg|20px|alt=M01|link=]] [[File:L01.svg|20px|alt=L01|link=]] [[File:A01.svg|20px|alt=A01|link=]] [[File:T03.svg|20px|alt=T03|link=]]<br />
|<br />
|-<br />
| EIGHT<br />
| <code>B02-M03-S03</code><br />
| [[File:B02.svg|20px|alt=B02|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:S03.svg|20px|alt=S03|link=]]<br />
|<br />
|-<br />
| NINE<br />
| <code>C05-M02-H02-A05-S02</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H02.svg|20px|alt=H02|link=]] [[File:A05.svg|20px|alt=A05|link=]] [[File:S02.svg|20px|alt=S02|link=]]<br />
|<br />
|-<br />
| TEN<br />
| <code>C05-M01-T02-M02-L01</code><br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M01.svg|20px|alt=M01|link=]] [[File:T02.svg|20px|alt=T02|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:L01.svg|20px|alt=L01|link=]]<br />
|<br />
|-<br />
| ELEVEN<br />
| <code>A01-H01-B01</code><br />
| [[File:A01.svg|20px|alt=A01|link=]] [[File:H01.svg|20px|alt=H01|link=]] [[File:B01.svg|20px|alt=B01|link=]]<br />
|<br />
|-<br />
| TWELVE<br />
| <code>C01-M02-H02-B04</code><br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H02.svg|20px|alt=H02|link=]] [[File:B04.svg|20px|alt=B04|link=]]<br />
|<br />
|-<br />
| '''EQUALS / clause spine'''<br />
| C02–M03–H03–C01<br />
| [[File:C02.svg|20px|alt=C02|link=]] [[File:M03.svg|20px|alt=M03|link=]] [[File:H03.svg|20px|alt=H03|link=]] [[File:C01.svg|20px|alt=C01|link=]]<br />
| Invariant medial sequence dividing left expression from result; reported as present in every equation clause. <ref name="Rubergskier2024" /><br />
|-<br />
| '''PLUS (binary addition)'''<br />
| A02–L01<br />
| [[File:A02.svg|20px|alt=A02|link=]] [[File:L01.svg|20px|alt=L01|link=]]<br />
| High-PMI operator cluster used in successor and complement constructions. <ref name="Rubergskier2024" /><br />
|-<br />
| '''MINUS (subtraction)'''<br />
| C05–M02–S02<br />
| [[File:C05.svg|20px|alt=C05|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:S02.svg|20px|alt=S02|link=]]<br />
| Distinct collocational profile mirroring the syntax of the addition lines. <ref name="Rubergskier2024" /><br />
|-<br />
| '''ONE (simplex unit)'''<br />
| C01–S03–C03–T03<br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:S03.svg|20px|alt=S03|link=]] [[File:C03.svg|20px|alt=C03|link=]] [[File:T03.svg|20px|alt=T03|link=]]<br />
| Recurrent bundle functioning as the unit “one”; used to advance the successor chain. <ref name="Rubergskier2024" /><br />
|-<br />
| '''PUNCTUATION (bound period)'''<br />
| P01 (final only)<br />
| [[File:P01.svg|20px|alt=P01|link=]]<br />
| Clause-final slash behaving as bound punctuation; not attested internally. <ref name="Rubergskier2024" /><br />
|-<br />
| '''×12 derivation (“dozen”)'''<br />
| –C01–M02–H02–B04 (right edge)<br />
| [[File:C01.svg|20px|alt=C01|link=]] [[File:M02.svg|20px|alt=M02|link=]] [[File:H02.svg|20px|alt=H02|link=]] [[File:B04.svg|20px|alt=B04|link=]]<br />
| Contiguous right-edge 4-gram treated as a derivational suffix forming multiples of twelve; composes with stems. <ref name="Rubergskier2024" /><br />
|}<br />
<br />
== Scholarly discussion ==<br />
Because the archaeological context of the longer inscription has not been publicly detailed, reception has been cautious. Supporters of the dozenal reading emphasise the conjunction of multiple independent diagnostics (final-only punctuation, a medial spine with near-zero variance, a selective right-edge four-gram, and complementary sums converging on the same target), arguing that chance alignment across all four is unlikely. Skeptics reply that without provenance, additional exemplars, or phonetic control, an arithmetic interpretation remains provisional and vulnerable to genre effects. Both sides agree on clear tests that could confirm or weaken the proposal: finding the slash P01 in non-final position; observing the putative ×12 four-gram away from clause edges; or documenting clauses that disrupt the medial spine while still behaving “arithmetically.”<ref name="Rubergskier2024" /><br />
<br />
== Nomenclature ==<br />
“Dozenal Primer Inscription” is a descriptive convenience used in secondary discussion and is not a claim about ancient self-designation. Alternative labels in circulation include “Dozenal arithmetic inscription,” “Twelve-base arithmetic inscription,” and “Kristiansen-coded arithmetic inscription.” For clarity and disambiguation within encyclopedic contexts, the present title foregrounds the proposed function (primer) and base (dozenal).<br />
<br />
== Relation to the Scapula Glyph Inscription ==<br />
The [[Scapula Glyph Inscription]] (KS-01) is much shorter but provided the stable sign labels and visual classes used in the transcription of the Dozenal Primer Inscription. KS-01 shows bipartite lines and a group-final slash divider consistent with the clause architecture proposed for the longer text, although by itself the scapula piece is too brief to display a full base-12 progression. Early notes on KS-01 also highlighted the need for direct examination and higher-quality imaging before drawing conclusions about material or chronology.<ref name="Kristiansen2023h" /><br />
<br />
== See also ==<br />
* [[Duodecimal]]<br />
* [[Numeral system]]<br />
* [[Mathematical notation]]<br />
* [[Undeciphered writing systems]]<br />
* [[Epigraphy]]<br />
* [[Paleography]]<br />
<br />
== References ==<br />
<references /></div>Mvuijlst