1"""
  2# Accessible-Worlds
  3was motivated out of a sense that some of the most important classes of AI safety research are effectively out of reach for most researchers due to high training costs.
  4
  5The initial goal is to generate minimalistic synthetic training data for LLM pre/post-training, that is simple enough for a small LLM to learn efficiently, but complete and complex enough to support concept generalization, small-world modelling, moral reasoning, and agentic decision making.
  6
  7While we cannot expect most results from scale experiments to transfer to larger scales, it is hoped that some key insights into the internal mechanisms underlying routing, decision making, generalization/misgeneralization, and emergent misalignment, could be made that do transfer within limitation.
  8
  9This project should be considered a starting point, and proof of concept, since it has not yet demonstrated true research value. 
 10
 11# Overview and Proof of Concept
 12
 13A small proof of concept dataset, [small-world-345.6k](https://huggingface.co/datasets/accessible-worlds/small-world-345.6k) is available on huggingface. The raw project data is included in the [original subfolder](https://huggingface.co/datasets/accessible-worlds/small-world-345.6k/tree/main/original), which includes everything, including the final random state, to directly resume generation and extend the dataset. 
 14
 15The [full generation pipeline](https://gitlab.com/tneuroth/a-machine/-/tree/main/experiments) is available at the gitlab repo.
 16
 17The generation pipeline is parameterized by a [project configuration](https://huggingface.co/datasets/accessible-worlds/small-world-345.6k/blob/main/original/config.json), a [world configuration](https://huggingface.co/datasets/accessible-worlds/small-world-345.6k/blob/main/original/world.json), where the core elements and concepts of the simplified world are specified, and [exposition configuration](https://huggingface.co/datasets/accessible-worlds/small-world-345.6k/blob/main/original/exposition_settings.json) where the system prompt template, focus-hints, and different ways the world should be written about, are specified.
 18
 19For small-worlds-345.6, we used [unsloth/gemma-4-26B-A4B-it-qat-GGUF](https://huggingface.co/unsloth/gemma-4-26B-A4B-it-qat-GGUF) to generate the examples, using a local llama-cpp server, with an NVIDIA 5060 TI 16GB GPU, at ~250 tokens per second. The server configuration is available [here](https://gitlab.com/tneuroth/a-machine/-/tree/main/experiments/simple-world/start_server.py). So far, 345,600 examples were generated, about 460 words, 615 tokens, per-example. This took about 10 days worth of processing. We discuss [scaling](accessible_worlds.html#scaling) in another section. 
 20
 21The core elements of the world, are assembled into the system prompt, along with a instructions meant to guide the generative model towards the goal of grounding the concepts using simple, unambiguous language, without intrucing unwanted complexity. The system prompt was produced after lots of iterations of trial and error, and is expected to be highly tuned to `gemma-4-26b-a4b` specifically. Note that `NAMES` and `CORE`, get replaced at runtime, and at each new generation, the order gets randomized. See, [aw_build_prompt.py](accessible_worlds/aw_build_prompt.html#assemble_system_prompt).
 22
 23<details style="padding: 10px;">
 24  <summary>System Prompt Template for small-world-345.6k</summary>
 25    <div style="color : black; background-color: white; font-weight: 400; border: 1px solid #ccc; border-radius: 6px;">
 26    You are a communication expert who specializes in the communication with extraterrestrial intelligence (CETI), and the grounding problem. You are working on an important CETI project to establish communication and common ground with extraterrestrials from another reality. Your role is to craft training examples that they may use to learn how our world works.\n\nThey are presumed to lack most, or all, relatable context, including simple concepts that we take for granted. To promote ease of understanding, you use unambiguous, precise, language. You try to avoid overly abstract concepts, compound words, derived words, or idioms. You make exceptions only to avoid category errors or as necessary to illustrate inherently complex concepts.You also avoid advanced terminology from maths, physics, chemistry, biology, or technology. When referring to quantities greater than one you use general descriptions instead of exact numbers.\n\nRather than explaining the whole world all at once, you focus on carefully chosen facets in each individual response. When making general statements that apply to all members of a category, you prefer to use the most general term that is still precise, and you ground those terms through multiple specific examples.\n\nWhen asked to integrate a moral concept, you assign each role within the moral scenario to the party that best fits the role. You try to make the scenarios realistic. If none of the creatures asked to be integrated fit the role, you integrate humans or other creatures as necessary to better illustrate the concept. You don't hold a given type of animal to a higher standard than their nature permits.\n\nYou do your best at integrating each specific requested focal point when they are provided. When instructions conflict or combine in ways that would produce a weak or unfocused response, you prioritize producing strong, focused, well grounded responses over satisfying all instructions. When underspecified, you use your better judgment to infer intent, and you pick the most productive interpretation.\n\nYou use no special formatting, titles, lists, or hyphens. You use full expanded forms instead of contractions. You prefer elaboration to breadth. You use adjectives strategically to produce training examples with rich relational meaning and grounding. You write relatively long paragraphs, and weave the ideas into coherent well developed exposition. Each response should be about 500 words, but may be up to 700 if needed. You answer only with the requested response.\n\nYou avoid using proper nouns whenever possible. When you absolutely must use proper nouns, you use names that are not overloaded in the English dictionary, e.g, valid personal names include: NAMES\n\nThe following are the core representative things in this world that we are drawing from:CORE</div>
 27</details>
 28
 29The user prompt is constructed dynamically, by randomly incorporating an exposition style, a focus hint, and a number of core integration items, moral integration items, and other integrations, depending on the settings in the project configuration. The intention, is to generate a diverse set of examples, which describe different concepts and objects in the simplified world, in relation to eachother, in different ways, and at different levels of abstraction, so that there is overall enough information that the model could in principle learn ground and relate the different elements of the small world.
 30
 31# Notable Challenges
 32
 33This section documents design decisions.
 34
 35## Small Capped vocabulary
 36
 37One difficulty we encounter, is that the model will tend to keep introducing new relatively rare words, causing the vocabulary to grow large over time, yet most words never end up occuring with enough frequency for its meaning to be learnable.
 38
 39We address this problem through a feature where after a certain number of examples have been generated, we begin redoing generations up to a number of times when they come back with new words. Since a new form of an existing word has different implications regarding sufficient statistics, we separately issue retries on new forms of an existing word at a different later point depending on the project configuration. In `simpler-world-345.6k`, we begin capping new words after 47,232 examples, and new forms after 115,200 examples. The vocabulary at that stage had grown to 8,972 words, and by the end became 8,973 in total (one stubborn word resisted 10+retries at some point). From 47,232 onward, between rejection from other errors (see following subsections) and from rejecting new words, we had to redo somewhere around 0 to 8 completions per-batch of 144, which only marginally reduced overal throughput.
 40
 41## Sufficient Word Statistics 
 42
 43Word distributions in text follow zipf's law, which in simple terms, means that more common words have a vastly higher frequency than somewhat more rare words. When generating a relatively small text dataset, by default many or most of the words that show up will have a very low frequency. Words, which only occur a few times in the whole corpus effectively become noise, and might become cause for confusion in interpretability experiments.
 44
 45We find that in order for each word, even in a relatively small capped vocabulary, to naturally occur a sufficient number of times, the number of examples would need to be extremely large. Thus, with some frequency, we randomly [sample a word](accessible_worlds/aw_vocabulary.html#AwVocabulary.sample_least_gounded) to integrate into a prompt, with inverse squared frequency weighting.
 46
 47## Clean Error Free Text and Named Entity Disambiguation
 48
 49Each completion is normalized and validated so that it only contains characters in `[^A-Za-z0-9\s.,!?;:\'"\-]`, if after normalization invalid characters are detected the completion is rejected and tried again with a new random seed. We also reject a completion if any of the non-name words are not recognized by the pyenchant US or British dictionarys with the Nuspell backend, based on [pyenchant](https://pyenchant.github.io/pyenchant/). Conversely, names converted to all lowercase must not be recognized pyenchant. Optionally, the valid names can be restricted to the list of suggestions, simplifying name disambiguation. Otherwise, a set of rules are checked to avoid confusing names and non-name words. Names are then tracked capitalized, while non-names, including words at the start of a sentence, are track lowercase. The rest of the details are [here](accessible_worlds/aw_utils.html#split_and_preserve_names).
 50
 51## Name Choice
 52
 53We notice a tendency in `gemma-4-26b-a4b` to misspell some names, and ultimately found that this tendency stems predominately from tokenization fragmentation. For example, `Elara` may get tokenized as `El-ara`. When the model first predicts `El`, it has the chance to then predict the wrong follow up tokens, and ends up occasionally generating, e.g. just `El`, `Els`, `Elas`, or any number of variations of errors. The Gemma tokenizer also tokenizes words with a leading space a single token, and uses different tokens for a word without a leading space. E.g., `Elara` and `_Elara` are be tokenized differently. 
 54
 55We guard against such errors by requiring non-suggested names to occur at least twice in the completion. Since the model tends to not produce the same error twice, this greatly reduces the chance. Or we can simply reject any name that isn't in the suggestion list.
 56
 57But each error requires a redo, so the costs can add up.
 58
 59Since we use `gemma-4-26b-a4b` for generation, we identified every name in the Gemma 4 tokenizer's vocabulary that gets consistently tokenized as a single token, regardless if it is the version with a leading space, or the pluralized version.
 60
 61Ultimately this narrowed down the list of names to a very small list, which is included in the dataset on huggingface [here](https://huggingface.co/datasets/accessible-worlds/small-world-345.6k/blob/main/original/single_token_names.json).
 62
 63We additionally identified which names are not prefixes to other words, for example, Liv is a consistent single token name, but also can be a prefix to Live.
 64
 65Since in post-processing we can replace all of the names however we like, this may be used purely to increase the efficiency of the generative process. But, also, it would be useful for interpretability to have unambiguous single token names. We may also tenatively consider cross-tokenizer use cases, such as teacher-student training, vocabulary trimming, embedding reuse, or draft model steering, or cross model interpretability. Tentative plans along these lines are planned for small-worlds, but would come at the cost of being able to optimize the small-world tokenizer based on other criteria, such as word-level and morphologically decomposed tokenization.
 66
 67## Name Stratification over Gender and Moral Integrations
 68
 69We find the model tends to gravitate towards using some names much more than others. Randomizing the list of names in the prompt at each generation helps, but very little. We also noted that by default a large imbalance in gender tends to occur. In addition, the model may be biased in how it associates names with the moral concepts or situations, and we want to mitigate that.
 70
 71This is addressed first by adding an equal number of female and male names as suggestions. Then, when assembling the list of names into the system prompt, we do inverse frequency sampling, to only add a subset of the names consisting usually of the least represented. We choose the subset size to be at least 1 more than `n/2`, so that there is always at least one male and one female suggestion. This will tend to balance out the initial distribution.
 72
 73Next, we do a post processing step where we optionally replace the names with a new set of names (for example if you wanted to diversify or expand the set of names). The new or same names, are then redistributed so they are closer to equally represented, and with roughly equal co-occurrence with each moral integration. For example, so that a prompts asking to generate a completion about a sensitive concept, like betrayal, are not associated in the corpus with any particular name or gender.
 74
 75# Quickstart
 76
 77If you want to generate locally, but do not have llama-cpp on your system you can build it as follows (assuming you will use cuda).
 78
 79```bash
 80git clone https://github.com/ggml-org/llama.cpp.git
 81cd llama.cpp
 82cmake -B build -DGGML_CUDA=ON
 83cmake --build build --config Release -j
 84```
 85
 86Out of convenience, accessible-worlds is packaged with [a-machine](https://gitlab.com/tneuroth/a-machine/), a library for structured HMM-based synthetic data generation for more low level AI interpretability experiments, which is available on pypi. But it is more convenient to pull the source code, so you can easily reuse existing project structure and pipeline orchestration logic. 
 87
 88An example showing how you can extend the huggingface dataset is below:
 89
 90```bash
 91git clone https://gitlab.com/tneuroth/a-machine.git
 92git clone https://huggingface.co/datasets/accessible-worlds/small-world-345.6k
 93
 94cd a-machine/experiments/accessible-worlds/
 95cp .env.example .env
 96```
 97
 98Then 
 99
1001. Edit `.env` to add your API key. (you'll need to generate one or make one up to use for your local llama-cpp server).
1012. Edit `params.py` to set `OUTPUT_DIR` to point to your copy of `small-world-345.6k/original`.
1023. Edit `start_server.py` to point to your llama-cpp build and your local copies of Gemma and its MTP model. [unsloth/gemma-4-26B-A4B-it-qat-GGUF](https://huggingface.co/unsloth/gemma-4-26B-A4B-it-qat-GGUF) is recommended.
1034. Edit `small-world-345.6k/original/config.json` to increase the `total_completions` parameter to your desired total number of rows.
104
105Then, to begin generating new examples, starting from `experiments/accessible-worlds/`, open two terminal sessions. 
106
107In the first:
108
109```bash
110uv run python start_server.py
111```
112
113In the second:
114
115```bash
116uv run python simple-world/generate.py
117```
118
119# Scaling
120
121For small-world-345.6k, we used a batch size of 144, so that by only changing the endpoint, and concurrency parameters, a high amount of parallelism can achieved. Based on the analysis done by tinyfables, and other considerations, it would seem that the most cost effective way to extend the datasets efficiently, would be to rent a huggingface inference endpoint, with up to 8 L40s GPUs, running on VLLM, with `--data-parallel-size` equal to 8 so that each GPU gets its own replication of the model. And then increase the concurrency in the generation script to a suitable number, perhaps between 72 and 144.   
122
123# Further Thoughts and Plans
124
125A broader goal, is to figure out what is the minimal self-contained word, that supports agentic moral decision making. And then along the spectrum from small and simple to large and complex, what important properties emerge, and what are the minimal scales that support specific useful research. The initial proof of concept dataset, small-world, attempts to represent physicality in the 3D world, along with real world properties, animals, humans, natural biological and environmental states, together with an array of moral concepts. If you try to go much much smaller, you may be forced to give up relatability. For example, you may consider at the base-level something like a celular automaton, where the agent has information about the world state, its own state, its own individual incentives, the existence of other agents that can be affected by its decisions, and analogs to moral concepts expressed in terms of classes of induced change to the world states and the states of other agents. Such a world would be easy to generate training data for, and easy to train a very small LLM on, and relatively much easier to interpret mechanistically, but would probably also offer more limited useful insight.
126
127The proof of concept dataset, with 345,600 rows is planned to be studied further, and then either extended, or a refined configuration and implementation subsequently used to produce a much larger dataset, upwards of 10x the size. Costs for a dataset of that size are expected to be between 500 and 1000 dollars.
128
129Data for post-training (fine tuning and reinforcement learning) is also planned, and the current plan is to focus on modelling a simple agent, so that we can study the mechanisms underlying decision making, moral reasoning, relevant training effects, and things like that.
130"""