{"id":24058094,"url":"https://github.com/uilicious/english-compiler","last_synced_at":"2025-07-11T16:38:51.149Z","repository":{"id":113361009,"uuid":"602951401","full_name":"uilicious/english-compiler","owner":"uilicious","description":"POC AI based Compiler, for converting english based markdown specs, into functional code","archived":false,"fork":false,"pushed_at":"2024-02-05T12:40:52.000Z","size":4252,"stargazers_count":293,"open_issues_count":2,"forks_count":16,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-07-04T07:45:17.981Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uilicious.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-17T09:48:14.000Z","updated_at":"2025-06-30T12:34:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"c6c0b0a6-da79-4736-b289-bcc0c80b27ce","html_url":"https://github.com/uilicious/english-compiler","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/uilicious/english-compiler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uilicious%2Fenglish-compiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uilicious%2Fenglish-compiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uilicious%2Fenglish-compiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uilicious%2Fenglish-compiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uilicious","download_url":"https://codeload.github.com/uilicious/english-compiler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uilicious%2Fenglish-compiler/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263499191,"owners_count":23476021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-09T05:55:34.402Z","updated_at":"2025-07-11T16:38:51.123Z","avatar_url":"https://github.com/uilicious.png","language":"JavaScript","funding_links":[],"categories":["\u003ca name=\"JavaScript\"\u003e\u003c/a\u003eJavaScript"],"sub_categories":[],"readme":"\u003e PS: The successor to this project is smol-dev-js : https://github.com/PicoCreator/smol-dev-js\n\n# The English Compiler\n\n\u003e English is all you need\n\nWe know that all great™ projects start with awesome™ detailed functional specifications.\nWhich is typically written in [English](https://esolangs.org/wiki/English), or its many other spoken language alternatives.\n\nSo what if, instead of writing code from functional specs, we simply compile it directly to code?\n\nInto a future, where we replace nearly everything, with just written text.\n\n![CLI help docs for the english](./notes/imgs/EnglishCommand-CLI-help.png)\n\nOn a smaller scale, instead of generating giant class files, it can convert smaller specifications like the following\n\n![Twitter db example spec](./notes//imgs/twitter-db-spec.png)\n\nInto the following code\n\n![Twitter db example code](./notes/imgs/twitter-db-code.png)\n\n\u003e Does it work? Yes  \n\u003e Is it production ready? No  \n\u003e \n\u003e This is simply a POC. However if you like to take it further, you may give it a try.\n\nFor more details, see the 3 minute youtube presentation\n\n[![The English Compiler : in 3 minutes](./notes/imgs/youtube-thumbnail.png)](https://www.youtube.com/watch?v=hdPG-avfpZo)\n\n# How is this \"better\" then ChatGPT ?\n\nExisting Open AI models, have an upper cap to the size of their input and output.\nThis limits their usage to small code snippets as of now.\n\nWe work around this limitation, by using ridiculous amount of impractical prompt chaining and engineering. Where we are be able to generate both entire applications across multiple files.\nOr really large (java) files. Or both.\n\n![Screenshot of a large wall of text and code, to represent how large the oauth2 spec is](./notes/imgs/oauth2-spec-and-code.png)\n\u003e An example of how large the OAuth2 integration specification and code with comment results into\n\nThis unfortunately means its a slow process\n\n![Flow chart of the long build processs](./notes/imgs/large-spec-build-process.png)\n\nWhere in order to build a large code file, multiple calls to the AI process needs to be done (almost every arrow in the digram, is an AI call)\n\n**If the chart does not make it clear, having 10+ AI calls per file: this giant process is slow as ass**\n\nBut the point is not in its practicality, but validating the practicality of a possible future. Where the AI is a potential new abstraction compiler layer, to existing modern programming language.\nJust as how modern programming languages are an abstract layer to operating system apis, which is in turn is an abstraction to machine code.\n\n# How do I install it?\n\nThe easiest way is to simply install it from NPM\n\n```.bash\nnpm install -g english-compiler\n```\n\n# How do I configure it?\n\nFrom the project you wish to build from, you should at minimum have a folder for the specs file, and the source code.\nYou can then setup an `english-compiler.jsonc` file, which should contain all the required settings. Including the openai API key.\n\nFor obvious reasons, please do not checkin your openai API key to a public repo\n\nThe following is an example of the settings\n```.jsonc\n{\n\t// Openai API key\n\t\"openai_apikey\": \"REPLACE-WITH-YOUR-ACTUAL-KEY-AND-DO-NOT-CHECKIN\",\n\n\t// Prompt caching dir, this can be used to cache and speed up the build process\n\t// especially when no specification (or code) changes occured\n\t//\n\t// This cache is also critical, in event that you hit the openAI rate limit \n\t// (or when their server becomes too busy with chatGPT). As it will abort the build.\n\t//\n\t// Caching the prompts, allow you to continue the build, without starting from scratch.\n\t\"prompt_cache_dir\": \"./prompt_cache\",\n\n\t// Specification directory, to scan for `*.spec.md` files\n\t\"spec_dir\": \"./spec\",\n\n\t// Source code output directory\n\t\"code_dir\": \"./src\",\n\n\t// Test code output directory (only supported for JS now)\n\t\"test_dir\": \"./test\",\n\n\t// Add some personality based remarks, set to false/null if you want to skip this\n\t// and save on token consumption (this feature is just for fun)\n\t\"personality\": \"Sassy \u0026 Sarcastic\"\n}\n```\n\n# Run one of our demo !\n\nNote that the demo, include a precomputed cache of the AI compilation process, so unless you change part of the spec file. You do not need to update the openai key in the settings.\n\nAll demos, also come preloaded with the specification files\n\n![Example of spec files](./notes/imgs/demo-spec-files.png)\n\nAnd the prebuilt code output (you can delete, and build again)\n\n![Example of code files](./notes/imgs/demo-code-files.png)\n\n\u003e Also yes, the output has some minor bugs here and there. This is a Proof-of-concept.\n\u003e\n\u003e I have spent over 4 hours, trying to slowly change the specs, and fix all the bugs. But the write-compile-test loop is just too damn slow. And I am out of time for the hackaton.\n\n## Demo 1 : Building a simple \"twitter clone\" demo\n\nThis is a simple complete application for a twitter clone, without login or authentication.\nIncluding both the UI, and the API endpoints.\n\nGo into the `demo/twitter-clone` folder\n\n**Ask the AI for suggestions on a spec file**\n\n`EnglishCompiler spec suggest spec/ui/index.spec.md`\n\n![CLI example output of the spec suggest command](./notes/imgs/CLI-spec-suggest.png)\n\n**Build a single spec file**\n\n`EnglishCompiler build file spec/core/db.spec.md`\n\n![CLI example of building one spec file](./notes/imgs/CLI-build-one.png)\n\n**Build all spec file**\n\n`EnglishCompiler build all`\n\n![CLI example of building all spec file](./notes/imgs/CLI-build-all.png)\n\nIf you want to really check, that it buidls the file feel free to delete the src directory, and run the build process.\n\n## Demo 2 : Larger java class\n\nThis is an example for a java class, which would have been too large, and goes beyond 4000+ tokens once you include the spec and code comments.\nIt is not possible to generate this directly via openAI api, without the tricks we have resorted to in this project.\n\nThere is only 1 file for this demostartion\n\nGo into the `demo/java-class` folder\n\n**Build all spec file**\n\n`EnglishCompiler build all`\n\n# What is the specification file format?\n\nThe specification folder, should contain `$NAME.spec.md` files that is a 1 to 1 mapping to individual code files.\n\nAt minimum it should have a markdown frontmatter, with the `type` parameter, for the language, for example\n\n```\n---\ntype: javascript\ntest: true\n---\n\n# DB module\n```\n\n`test` is an optional parameter (only supports javascript), that when enabled, will attempt to generate a relevent test script through a seperate process. To avoid contaminating the test code from the source code, this is done in isolation.\n\nFrom then onwards, the rest is really up to you, on how you want to write your markdown spec\n\n# FAQ \n\n### Can I use any other language besides English?\n\nProbably yea, whatever the openAI model support (or future LLM model support) should work in theory\n\n### Instead of writing a spec for each code file, isn't it possible to write a higher level specification file?\n\nThere was some experimentation done on this, but due to time constraints, it was decided to map them in 1-to-1 manner.\nI dun see why not (besides more AI calls), as we can take a similar approach to how we deal with large java classes, by doing a prelimary step of asking the AI how many files it need to make from this one spec file.\n\n### How is this related to Uilicious, or UI testing?\n\nWe built our own AI model for test and code generation, and the original concept for this project was to read product specification, and convert it to UI and unit tests, using our finetuned AI model (technically, we use both a custom finetune model, and OpenAI models, in a prompt chain)\n\nHowever it was very quickly shown, that it will be too damn slow, and not commercially viable in its current state. So the original internal POC, was subsequently rewritten (removing any confidential code, and keys) to the \"English Compiler\" for this opensource release during the hackaton.\n\nSidenote: The OAuth2 specification file, is a real specification file that was written, and used as one of our original internal demos.\n\n### Is it possible, to make this possible?\n\nWell we are working on it, by trying to build a model that is \"not smarter\" with more parameters, but is able to have large contextual token memory. \nThis is loosely based on \n- SalesForce codegen model and dataset ( https://github.com/salesforce/CodeGen )  \n- The Pile ( https://pile.eleuther.ai/ ) \n- EleutherAI 20B ( https://blog.eleuther.ai/announcing-20b/ ) \n- xP3 instructional tuning dataset ( https://huggingface.co/datasets/bigscience/xP3 )\n- (to add) The Stack ( https://huggingface.co/datasets/bigcode/the-stack )\n\nWe are however on a really tight budget, and are fundraising to help speed things up. \nFirst for the use of testing, which has a more immediate practical use and require less contextual memory and code complexity (AKA can use an inferior model). To eventually codegen in general.\n\n### Such an inefficent compiler, can't possibly ever be useful\n\nWell you are probably right, for its current iteration. It has bugs, and may fail to compile, when chatGPT is overloaded.\n\nBut the last time I worked on \"useless compiler\" 5 years ago, that was never meant for production usage. [GPU.js](https://gpu.rocks/#/)\nIt ended up running entire neural networks, and digital art installations, on thousands of browsers.\n\nThe original [GPU.js](https://github.com/gpujs/gpu.js) compiler was no different, and equally broken. Or technically worse (it was only compatible with some GPUs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuilicious%2Fenglish-compiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuilicious%2Fenglish-compiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuilicious%2Fenglish-compiler/lists"}