Cataclysm: a Python library that generates code for functions you never wrote

What Cataclysm actually solves for a Python developer

The pitch is narrow and specific. You write a call to a function that does not exist yet, give it a descriptive name and arguments, and Cataclysm asks OpenAI's GPT-4 to write the body. The README frames this as "the end of mortal coding" and shows a one-liner that returns Wikipedia-style italicized phrases from a page title, a function the author never implemented by hand. The intended user is someone in a REPL or a notebook who wants a throwaway helper now and does not want to write it. It is not a code completion plugin, and it is not a static generator you run at build time. The generation happens when the call is made, which is why the README spends so much space on warnings rather than features. The library is MIT licensed, version 0.1.2, and requires Python 3.10 or newer according to pyproject.toml.

How consume() and doom intercept a missing function

There are two entry points and the difference matters. Calling consume(globals()) installs a hook over the module's global namespace, so any name lookup that fails triggers generation. From that point on, an unrecognized function anywhere in that module gets an AI-written body. The README is explicit that this mode is for notebooks and interactive sessions and "not designed to be used in libraries or apps." The doom module is the recommended path: you import it and call a function on it, such as doom.first_prime_with_3_digits(), so generation is opt-in per call rather than ambient. Doom also exposes doom.impending, which returns the generated code as a string without executing it, and doom.chosen, which the README describes as a way to ensure released code never tries to generate anything. Generated bodies are cached locally per function signature. The README says they typically land in ./datafiles/cataclysm/code/<functionname>.yml, and that the second and later calls reuse the cache, which is both a speed measure and a cost measure. When a freshly generated body raises, the README states it regenerates once and retries; if that second attempt also fails, you are told to add more guidance or install more modules.

Installing Cataclysm and generating your first function

Installation is two steps. The package comes from PyPI, and the cataclysm command copies the default datafiles into your project so the prompt templates and cache directories exist. Run this in your project directory:

pip install cataclysm
cataclysm init

The init step matters because the generation prompts live in datafiles, and the README notes you can edit datafiles/plunkylib/petitions/CataclysmQuery.yml to switch models. Next, configure the API key. The init command writes a template, or you can copy env.template.cataclysm to .env in your working directory and fill it in:

OPENAI_API_KEY = "ADD_YOUR_OPENAI_KEY"

With the key in place, the smallest real use is the doom path from the README. Import doom and call a function that does not exist; the name and its arguments are the whole specification.

>>> from cataclysm import doom
>>> uhoh = doom.first_prime_with_3_digits()
>>> print(uhoh)
101

What you should see is the value 101, and a new YAML file under datafiles/cataclysm/code/ holding the generated implementation. If you want to read the code before it runs, use doom.impending.say_stuff("YOU ARE DOOMED") instead, which the README says returns an unexecuted code dump.

The case against putting Cataclysm in a library

The README's own warning is the strongest limitation here: "The cataclysm could destroy you and everything you hold dear." That is marketing voice, but the technical content behind it is real. Generated code is exec'd in your process. The prompt is written to discourage local I/O unless it is explicitly requested, and the README says the model "could be tricked, confused, misled, or gain an unexpected hunger for destruction." Treat that as an admission that the sandbox is a prompt, not an interpreter boundary. The second limitation is reproducibility. A function with no cached body will call the API, and the body you get depends on the model, the prompt file, and the moment. That is fine in a notebook and unacceptable in a distributed package, which is why the README recommends shipping the generated code files and using doom.chosen to disable live generation in released code. Third, the retry behaviour is shallow. One regeneration on exception, then it gives up. A function that needs a dependency you have not installed will not be fixed by a second attempt. Fourth, the project depends on OpenAI specifically. The README says it also works with gpt-3.5-turbo if you edit the petition file to reference CataclysmLLMParams_3-5, and that the weaker model is faster and cheaper but less impressive. There is no local model path documented.

Cataclysm against langchain and template code generators

The README itself places Cataclysm near langchain, describing plunkylib as "a yaml-friendly layer not totally unlike langchain." The difference in approach is where the generation sits. Langchain-style code builds a chain you call explicitly with a prompt and parses the text output; you own the boundary between model and program. Cataclysm moves the boundary into the Python name resolution itself, so the model output becomes a function body that the interpreter then runs. That is a much shorter path from prompt to execution and a much harder one to audit, which is exactly why the project offers doom.impending and doom.chosen as escape hatches. If your goal is a deterministic generator, a Jinja or cookiecutter template is the honest alternative: it produces the same file every time, needs no API key, and cannot hallucinate an import. Cataclysm is for the opposite situation, where you cannot write the template because you do not know what the function should do until you describe it in English.

Maintenance, dependencies and the MIT licence

The repository was last pushed on 2026-08-16, so it is recent, but there are no releases retrieved and the version in pyproject.toml is 0.1.2, which reads as early. The dependency set is small and pinned loosely: plunkylib ^0.1.4, loguru ^0.6.0, openai ^0.27.2, and datafiles ^2.1, with Python ^3.10. The openai pin is worth noticing. Version 0.27.x is the pre-1.0 line of the OpenAI Python SDK, and the README's FAQ says the API is called through plunkylib rather than directly, so an upgrade to the modern openai client would flow through that layer first. If you depend on Cataclysm, that transitive pin is the thing most likely to break your environment. The MIT licence is permissive: you can use, modify, and redistribute it, including commercially, provided the copyright notice and permission notice are included. Nothing in the repository suggests a separate terms document for the generated code, so the licence of whatever the model produces is a question the README does not answer. That is a gap worth raising with a lawyer if you plan to ship generated bodies, not something this article can settle.

Where Cataclysm fits and where it does not

The example apps in the repository, examples/hangman/ and examples/image_resizer/, suggest the author's own use is small utilities rather than production services. The hangman and image resizer cases are the shape of problem Cataclysm handles well: a bounded function with an obvious name, a clear input, and a result you can eyeball in seconds. The Dijkstra example in the README, find_shortest_path_dijkstra(graph, "A", "D") returning ['A', 'C', 'B', 'D'], is the ceiling of what the documentation claims: a known algorithm with a known correct answer, so you can check the output. Where it does not fit is anything with side effects you cannot inspect, anything that runs on untrusted input, and anything you distribute. The README's own FAQ says the author is considering a more powerful hosted API for people without an OpenAI account, which means the current answer for that group is that there is no supported path. If you need generated code to be identical across machines and runs, this is the wrong tool; the cache file is a convenience, not a guarantee.

Editorial conclusion

Adopt Cataclysm only for notebooks, prototypes, and internal experiments where a wrong function body costs you nothing, and where you accept that generated code runs in your process. Do not put it behind a public API or in a library you distribute, because consume() rewrites globals() and the README states it is not designed for libraries or apps. Before anything else, verify that doom.chosen can freeze the generated code and that datafiles/cataclysm/code/<functionname>.yml contains the bodies you expect, since that directory is what you would ship instead of live generation.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Mattie/cataclysm on GitHub
4. README