{"id":14964650,"url":"https://github.com/lukechilds/humanscript","last_synced_at":"2025-04-10T02:22:51.812Z","repository":{"id":186730330,"uuid":"674675344","full_name":"lukechilds/humanscript","owner":"lukechilds","description":"A truly natural scripting language","archived":false,"fork":false,"pushed_at":"2024-05-28T07:22:26.000Z","size":94,"stargazers_count":230,"open_issues_count":2,"forks_count":14,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-29T09:00:41.163Z","etag":null,"topics":["ai","artificial-intelligence","gpt","gpt-4","inferpreter","interpreter","language","llama","llama2","llm","machine-learning","nlp","openai","openai-api","scripting-language"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/lukechilds.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-08-04T13:59:29.000Z","updated_at":"2024-10-12T20:30:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"bd2c49b7-b3ac-4fa0-a1ef-4d6e66d8b2c8","html_url":"https://github.com/lukechilds/humanscript","commit_stats":{"total_commits":38,"total_committers":1,"mean_commits":38.0,"dds":0.0,"last_synced_commit":"fd755af82503269f2138a9afad27093662302b70"},"previous_names":["lukechilds/humanscript"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukechilds%2Fhumanscript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukechilds%2Fhumanscript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukechilds%2Fhumanscript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukechilds%2Fhumanscript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukechilds","download_url":"https://codeload.github.com/lukechilds/humanscript/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247819948,"owners_count":21001394,"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":["ai","artificial-intelligence","gpt","gpt-4","inferpreter","interpreter","language","llama","llama2","llm","machine-learning","nlp","openai","openai-api","scripting-language"],"created_at":"2024-09-24T13:33:34.798Z","updated_at":"2025-04-10T02:22:51.791Z","avatar_url":"https://github.com/lukechilds.png","language":"Shell","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.webp\" height=\"150\" /\u003e\n\u003c/p\u003e\n\n# humanscript\n\n\u003e A truly natural scripting language\n\nhumanscript is an inferpreter. A script interpreter that infers the meaning behind commands written in natural language using large language models. Human writeable commands are translated into code that is then executed on the fly. There is no predefined syntax, humanscripts just say what they want to happen, and when you execute them, it happens.\n\nThe humanscript inferpreter supports a wide range of LLM backends. It can be used with cloud hosted LLMs like OpenAI's GPT-3.5 and GPT-4 or locally running open source LLMs like Llama 2.\n\n## Example\n\nThis is a humanscript called `tidy-screenshots`. It takes an unorganised directory of screenshots and organises them into directories based on the month the screenshot was taken.\n\n```shell\n#!/usr/bin/env humanscript\n\nloop over all files (ignoring directories) in $HOME/Screenshots\n\nmove each file into a subdirectory in the format year-month\n\nwhile the task is running show an ascii loading spinner\n\nshow how many files where moved\n\nshow the size of each subdirectory\n```\n\nIt can be executed like any other script.\n\n```shell\n$ ./tidy-screenshots\nMoved 593 files.\n364K    2023-08\n2.3M    2023-02\n5.4M    2022-09\n5.8M    2023-03\n6.9M    2022-07\n7.4M    2023-04\n 10M    2023-01\n 12M    2022-01\n 13M    2022-10\n 14M    2022-03\n 16M    2022-11\n 16M    2022-12\n 18M    2022-02\n 19M    2021-11\n 20M    2021-12\n 23M    2021-09\n 23M    2022-05\n 28M    2023-07\n 30M    2022-04\n 30M    2023-05\n 30M    2023-06\n 35M    2022-06\n 38M    2021-10\n 66M    2022-08\n```\n\nThe LLM inferpreted the humanscript into the following bash script at runtime.\n\n```shell\n#!/usr/bin/env bash\n\nspinner() {\n    local i sp n\n    sp='⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'\n    n=${#sp}\n    while sleep 0.1; do\n        printf \"%s\\r\" \"${sp:i++%n:1}\"\n    done\n}\n\nspinner \u0026\n\nspinner_pid=$!\n\nmoved_count=0\n\nfor file in \"$HOME/Screenshots\"/*; do\n    if [ -f \"$file\" ]; then\n        dir=\"$HOME/Screenshots/$(date -r \"$file\" \"+%Y-%m\")\"\n        mkdir -p \"$dir\"\n        mv \"$file\" \"$dir\"\n        ((moved_count++))\n    fi\ndone\n\nkill \"$spinner_pid\"\n\necho \"Moved $moved_count files.\"\n\ndu -sh \"$HOME/Screenshots\"/* | sed \"s|$HOME/Screenshots/||\"\n```\n\nThe code is streamed out of the LLM during inferpretation and executed line by line so execution is not blocked waiting for inference to finish. The generated code is cached on first run and will be executed instantly on subsequent runs, bypassing the need for reinferpretation.\n\nYou can see it in action here:\n\n![](demo.svg)\n\n## Usage\n\n### Install humanscript\n\nYou can run humanscript in a sandboxed environment via Docker:\n\n```shell\ndocker run -it lukechilds/humanscript\n```\n\nAlternatively you can install it natively on your system with Homebrew:\n\n```shell\nbrew install lukechilds/tap/humanscript\n```\n\nOr manually install by downloading this repository and copy/symlink `humanscript` into your PATH.\n\n\u003e Be careful if you're running humanscript unsandboxed. The inferpreter can sometimes do weird and dangerous things. Speaking from experience, unless you want to be doing a system restore at 2am on a saturday evening, you should atleast run humanscripts initially with `HUMANSCRIPT_EXECUTE=\"false\"` so you can check the resulting code before executing.\n\n### Write and execute a humanscript\n\nhumanscript is configured out of the box to use OpenAI's GPT-4, you just need to add your API key.\n\nWe need to add it to `~/.humanscript/config`\n\n```shell\nmkdir -p ~/.humanscript/\necho 'HUMANSCRIPT_API_KEY=\"\u003cyour-openai-api-key\u003e\"' \u003e\u003e ~/.humanscript/config\n```\n\nNow you can create a humanscript and make it executable.\n\n```shell\necho '#!/usr/bin/env humanscript\nprint an ascii art human' \u003e asciiman\nchmod +x asciiman\n```\n\nAnd then execute it.\n\n```shell\n./asciiman\n  O\n /|\\\n / \\\n```\n\n## Configuration\n\nAll environment variables can be added to `~/.humanscript/config` to be applied globally to all humanscripts:\n\n```shell\n$ cat ~/.humanscript/config\nHUMANSCRIPT_API_KEY=\"sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\nHUMANSCRIPT_MODEL=\"gpt-4\"\n```\n\nor on a per script basis:\n\n```shell\n$ HUMANSCRIPT_REGENERATE=\"true\" ./asciiman\n```\n\n### `HUMANSCRIPT_API`\n\nDefault: `https://api.openai.com/v1`\n\nA server following OpenAI's Chat Completion API.\n\nMany local proxies exist that implement this API in front of locally running LLMs like Llama 2. [LM Studio](https://lmstudio.ai/) is a good option.\n\n```shell\nHUMANSCRIPT_API=\"http://localhost:1234/v1\"\n```\n\n### `HUMANSCRIPT_API_KEY`\n\nDefault: `unset`\n\nThe API key to be sent to the LLM backend. Only needed when using OpenAI.\n\n```shell\nHUMANSCRIPT_API_KEY=\"sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n```\n\n### `HUMANSCRIPT_MODEL`\n\nDefault: `gpt-4`\n\nThe model to use for inference.\n\n```shell\nHUMANSCRIPT_MODEL=\"gpt-3.5\"\n```\n\n### `HUMANSCRIPT_EXECUTE`\n\nDefault: `true`\n\nWhether or not the humanscript inferpreter should automatically execute the generated code on the fly.\n\nIf false the generated code will not be executed and instead be streamed to stdout.\n\n```shell\nHUMANSCRIPT_EXECUTE=\"false\"\n```\n\n### `HUMANSCRIPT_REGENERATE`\n\nDefault: `false`\n\nWhether or not the humanscript inferpreter should regenerate a cached humanscript.\n\nIf true the humanscript will be reinferpreted and the cache entry will be replaced with the newly generated code. Due to the nondeterministic nature of LLMs each time you reinferpret a humanscript you will get a similar but slightly different output.\n\n```shell\nHUMANSCRIPT_REGENERATE=\"true\"\n```\n\n## License\n\nMIT © Luke Childs\n","funding_links":[],"categories":["Shell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukechilds%2Fhumanscript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukechilds%2Fhumanscript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukechilds%2Fhumanscript/lists"}