{"id":20081304,"url":"https://github.com/fedenunez/tulp","last_synced_at":"2025-07-01T07:04:05.375Z","repository":{"id":150363522,"uuid":"621108399","full_name":"fedenunez/tulp","owner":"fedenunez","description":"Tulp is a command-line tool that can help you create and process piped content using the power of ChatGPT directly from the terminal.","archived":false,"fork":false,"pushed_at":"2025-04-01T09:38:52.000Z","size":336,"stargazers_count":19,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-11T22:21:42.532Z","etag":null,"topics":["chatgpt","chatgpt-api","console","llm","nlp","shell","unix-shell"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fedenunez.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,"zenodo":null}},"created_at":"2023-03-30T02:20:37.000Z","updated_at":"2025-03-23T05:52:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"d4601660-f197-45e3-bf27-53ab0f09bf8f","html_url":"https://github.com/fedenunez/tulp","commit_stats":null,"previous_names":["fedenunez/tulip"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/fedenunez/tulp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fedenunez%2Ftulp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fedenunez%2Ftulp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fedenunez%2Ftulp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fedenunez%2Ftulp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fedenunez","download_url":"https://codeload.github.com/fedenunez/tulp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fedenunez%2Ftulp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262916575,"owners_count":23383883,"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":["chatgpt","chatgpt-api","console","llm","nlp","shell","unix-shell"],"created_at":"2024-11-13T15:38:34.117Z","updated_at":"2025-07-01T07:04:05.324Z","avatar_url":"https://github.com/fedenunez.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TULP: TULP Understands Language Promptly \n\nTULP is a command-line tool inspired by POSIX utilities, designed to help you **process**, **filter**, and **create** data in the realm of Artificial Intelligence. It now includes enhanced capabilities to utilize various AI APIs, such as groq, ollama, anthropic, and gemini.\n\nWith TULP, you can leverage the power of multiple AI models by piping standard input content directly to these models and receiving the output in your shell.\n\n[![Watch the TULP demo video](https://markdown-videos.deta.dev/youtube/mHAvlRXXp6I)](https://www.youtube.com/watch?v=mHAvlRXXp6I)\n\n## Installation\n\nTo install TULP, run:\n```bash\npip install tulp\n```\nTo keep it up to date, use:\n```bash\npip install --upgrade tulp\n```\n\n**Note:** If you encounter issues with google-generativeai dependencies during installation, try upgrading pip:\n```bash\npip install --upgrade pip\n```\n\n## Usage\n\nTULP offers three main operation modes:\n\n1. **Request Mode:** Process a user request.\n   ```bash\n   tulp [Your request or question]\n   ```\n\n2. **Stdin Processing Mode:** Process or filter all stdin input based on user instructions, outputting the processed data to stdout.\n   ```bash\n   cat [MYFILE] | tulp [Processing instructions in natural language]\n   ```\n\n3. **Code Interpretation Mode:** Add `-x` to any of the previous operations, and TULP will attempt to **create, debug, and execute** a program to fulfill the request.\n   ```bash\n   cat examples/titanics.csv | tulp -x how many persons survived\n   ```\n\nIn all cases, TULP outputs answers to standard output and any additional information to standard error. You can safely pipe the output to a file or another command, while still receiving all information and errors on stderr.\n\n**Important:** If your input exceeds 5000 characters, it will be split into multiple chunks and processed by the selected AI model in multiple requests. The result quality may vary depending on the task (e.g., translations or grammatical corrections work well, summarizing may not). TULP performs best with inputs under 5000 characters.\n\nBy default, TULP uses **gpt-4o** for its cost-effectiveness and speed. For complex tasks, specifying the model is recommended:\n```bash\ntulp --model {model_name} {a complex task}\n```\n\n### Options\n\n```\nusage: tulp [-h] [-x] [-w W] [--model MODEL] [--max-chars MAX_CHARS] [--cont CONT] [-v] [-q] [--groq_api_key GROQ_API_KEY]\n            [--ollama_host OLLAMA_HOST] [--anthropic_api_key ANTHROPIC_API_KEY] [--openai_api_key OPENAI_API_KEY]\n            [--openai_baseurl OPENAI_BASEURL] [--gemini_api_key GEMINI_API_KEY]\n            ...\n\nTULP Understands Language Promptly:\nA command-line tool inspired by POSIX utilities, designed to help you\n**process**, **filter**, and **create** data in the realm of Artificial\nIntelligence.\n\nTULP supports different backends and models, automatically selecting the backend for each model. Supported models include:\n\n   - groq.* : Any groq model ID prefixed with 'groq.', using the GROQCLOUD API and requiring a GROQ_API_KEY. Check available models at https://console.groq.com/docs/models\n   - ollama.* : Any ollama model prefixed with 'ollama', running on the ollama_host.\n   - claude-.* : Any Anthropic claude model (https://docs.anthropic.com/claude/docs/models-overview), requiring an ANTHROPIC_API_KEY\n   - gpt-.* : Any OpenAI model (https://platform.openai.com/docs/models), requiring an openai_api_key\n   - gemini.* : Any Google gemini model (https://ai.google.dev/gemini-api/docs/models/gemini), requiring a gemini_api_key\n\nPositional arguments:\n  request               User request, instructions written in natural language\n\nOptions:\n  -h, --help            Show this help message and exit\n  -x                    Allow TULP to create a program and execute it to fulfill the task (code interpret)\n  -w W                  Write the output (or the created program for execution) to a file. If the file exists, a backup will be created before overwriting it.\n  --model MODEL         Select the OpenAI LLM model to use (default: gpt-4-turbo)\n  --max-chars MAX_CHARS Number of characters per message chunk per request (Default 40000)\n  --cont CONT           Automatically ask the model to continue until it finishes answering the request up to the given times\n  -v                    Be verbose!\n  -q                    Be quiet! Only print the answer and errors.\n  --groq_api_key GROQ_API_KEY\n                        GROQ cloud API KEY\n  --ollama_host OLLAMA_HOST\n                        Define custom ollama host, default is http://127.0.0.1:11434\n  --anthropic_api_key ANTHROPIC_API_KEY\n                        Anthropic API key\n  --openai_api_key OPENAI_API_KEY\n                        OpenAI cloud API KEY\n  --openai_baseurl OPENAI_BASEURL\n                        Change the server, e.g., use http://localhost:11434/v1/ to connect to your local ollama server\n  --gemini_api_key GEMINI_API_KEY\n                        Gemini cloud API KEY\n```\n\n## Configuration\n\nThe configuration file is located at `~/.tulp.conf`.\n\nConfigurable parameters include:\n- **LOG_LEVEL**: The log level of TULP. Options are DEBUG, INFO, WARNING, ERROR, and CRITICAL. Default is INFO.\n- **API_KEYS**: API keys for supported AI models (OpenAI, GROQ, Ollama, Anthropic, Gemini). Default is an empty string for each.\n- **MAX_CHARS**: Maximum number of characters processed in one chunk. Default is 40000.\n- **MODEL**: The AI model used by TULP. Default is gpt-4o, but other models are available.\n\nThese settings can be overridden by environment variables using the prefix TULP_ or by command-line arguments described above. As environment variables, they become: TULP_LOG_LEVEL, TULP_API_KEYS, TULP_MAX_CHARS, or TULP_MODEL. Command-line arguments override environmental variables and the configuration file.\n\nExample configuration file with default values:\n```INI\n[DEFAULT]\nLOG_LEVEL = INFO\n${MODEL}_API_KEYS = \u003c\u003c\u003cYOUR API KEYS FOR GROQ, OLLAMA, ANTHROPIC, OPENAI, GEMINI\u003e\u003e\u003e\nMAX_CHARS = 40000\nMODEL = gpt-4o\n```\n\n## Examples\n\nTULP's usage is versatile. Here are some examples for inspiration:\n\n### Random\n\n#### The Meaning of Life for Different Models\n\n```\n+ tulp -q --model gpt-4-turbo tell me the meaning of life in just 3 words\n42, not known\n\n+ tulp -q --model gpt-3.5-turbo tell me the meaning of life in just 3 words\nLive, love, learn.\n\n+ tulp -q --model claude-3-opus-20240229 tell me the meaning of life in just 3 words\nLove conquers all.\n\n+ tulp -q --model gemini-1.5-pro-latest tell me the meaning of life in just 3 words\nThe answer is 42.\n\n+ tulp -q --model groq.gemma-7b-it tell me the meaning of life in just 3 words\nThe meaning of life is to find purpose and fulfillment in the present moment.\n\n+ tulp -q --model groq.llama3-70b-8192 tell me the meaning of life in just 3 words\nFind Your Purpose\n\n+ tulp -q --model groq.mixtral-8x7b-32768 tell me the meaning of life in just 3 words\nImpossible task.\n\n+ tulp -q --model ollama.phi3:instruct tell me the meaning of life in just 3 words\necho \"Meaning of Life\"\n```\n\n#### Create a Plot from Raw Memory Output Printed by gdb\n\nCommand:\n```bash\ncat \u003c\u003cEOF | tulp convert this to a python list of 2 element tuples |  tulp -x write a python function to scatter plot these points using matplotlib  \n(gdb) p *polygon._points._M_ptr._M_impl._M_start@4\n$21 = {{x = 0.441429973, y = -0.176619753}, {x = 0.476210177, y = -0.104575738}, {x = 0.674865067, y = -0.0814191923}, {x = 0.640084863, y = -0.199776307}}\nEOF\n```\n\nResult:\n\n![matplotlib @rela](./examples/rela_plot.png)\n\n### Grammatical and Syntax Correction of Clipboard Content in Linux\n\nThe corrected version will be in the clipboard:\n```bash\nxsel -b | tulp fix my english | xsel -b\n```\n\n### Typical Unix Tooling Replacement\n\n#### Sed\n```bash\ncat README.md | tulp replace all the occurrences of TULP for **TULP**\n```\n\n#### Awk\n```bash\ncat README.md | tulp print the second word of each line\n```\n\n#### Advanced Grep\n```bash\ncat tulp.py | tulp print the name of the functions and also the return line \n```\n\n### Grammatical and Syntax Corrections\n```bash\ncat README.md | tulp fix all the typos, syntax and grammatical errors \u003e README.fix.md\n```\n\nOr even better:\n```bash\ncat README.md | TULP_MAX_CHARS=10000 TULP_MODEL=gpt-4 tulp fix all the typos, syntax and grammatical errors \u003e README.fix.md\n```\n\n### Translations\n```bash\ncat README.md | tulp translate to Spanish \u003e README.es.md\n```\n\n### Data Filtering from Formatted Input\n\n#### CSV\n```bash\ncat list.csv | tulp print only the second column\nCount\n3\n1\n2\n```\n\n#### JSON to CSV\n```bash\ncat persons.json | tulp 'list the names and ages of each person in a csv table, using ; as separator'\n```\n\n### Data Creation and Extraction from Unstructured Data\n\nA story of oranges and friends:\n```bash\nfede@liebre:~/repos/tulp$ tulp write a poem that names 3 persons \\(given each a name\\) and list how they shared 10 oranges | tee examples/oranges_poem.txt\nRoses are red,\nViolets are blue,\nHere's a poem,\nAbout sharing oranges too.\n\nThere were three friends,\nWhose names were Ann, Ben, and Sue,\nThey had 10 oranges,\nAnd didn't know what to do.\n\nAnn suggested they split them,\nEqually, three each,\nBut Ben said that wasn't fair,\nAs Sue was too weak.\n\nSo they decided to give Sue,\nAn extra orange or two,\nAnd split the rest evenly,\nSo everyone had a fair view.\n\nAnd that's how Ann, Ben, and Sue,\nShared their 10 oranges,\nWith kindness and fairness,\nAnd no one had any grudges.\n\nfede@liebre:~/repos/tulp$ cat examples/oranges_poem.txt | python3 ./tulp.py write a list of persons and the number of oranges that they have as csv\nAnn,3\nBen,3\nSue,4\n```\n\n## Origin of the Name\n\nI used `tulp.py` to create \"TULP\". In some way, everything is recursive in \"TULP\", so it makes sense to use a recursive acronym.\n\nAfter several iterations with `tulp.py`, \"TULP\" and I decided that the best name would be \"TULP\", and this is how we decided what \"TULP\" stands for:\n```bash\nfede@liebre:~/repos/openai/tulp$ python3 ./tulp.py \"TULP is a recursive acronym naming an opensource posix tool that processes stdin input according to natural language instructions, processing the input by instructing an artificial intelligence. Write some options of what TULP could stand for as recursive acronym\"\nTULP could stand for:\n- TULP Understands Language Perfectly\n- TULP Uses Language to Process\n- TULP Understands Language Promptly\n- TULP Utilizes Language for Processing\n- TULP Unravels Language Precisely\n```\n\n## Why?\n\nAs a heavy user of Unix tools like awk, jq, sed, and grep, I relied on them heavily. However, with the advent of ChatGPT, I began using GPT for tasks I previously used Unix tools for. I felt the inconvenience of cut \u0026 paste and wanted a faster way to do it directly from the terminal, leading to the creation of `tulp`.\n\n## Changelog\n\n### v2.6.3 | 2024-09-16\n- Adds support to openai chatgpt-\\* models, like `chatgpt-4o-latest`, and the option to use \"openai.\" prefix to select any future openai model.\n\n- Improved output end detection and cleaning of spurious code blocks.\n\n### v2.6.2 | 2024-08-29\n- Improved output end detection and cleaning of spurious code blocks.\n\n### v2.6.1 | 2024-08-29\n- Changed gemini dependencies due to installation issues on some platforms.\n\n### v2.6 | 2024-08-29\n- **Refactor:** Renamed internal blocks, now the LLM knows the input as stdin.\n- **New Features:** \n  - Added `--inspect-dir` option to save each iteration with the LLM to a directory for review, aiding in debugging and understanding interactions.\n- **Bug Fixes:** Corrected a typo in the codebase.\n- **Enhancements:** \n  - Integrated Gemini API dependencies to support interactions with Gemini LLMs.\n  - Increased default maximum characters for responses to handle longer outputs.\n  - Updated error messages for token limit exceedance to provide better context and guidance.\n\n### v2.5 | 2024-07-27\n- Fixed the --cont issue.\n- Added Gemini API dependencies.\n- Increased the default maximum characters.\n\n### v2.3 | 2024-05-19\n- Added -cont option to allow TULP to automatically request the LLM to continue if an incomplete response is found.\n- Added automatic handling of RECITATION for Gemini LLM.\n\n### v2.2 | 2024-05-14\n- Fixed code execution (-x option).\n\n### v2.1 | 2024-05-14\n- Improved formatting of messages for Gemini.\n- Changed to use gpt-4o model by default.\n\n### v2.0 | 2024-05-04\n- Added support for groq, ollama, anthropic, and gemini AI models.\n- Changed to use gpt-4-turbo model by default.\n\n### v1.0 | 2024-02-14\n- Changed to use gpt-4-0125-preview model by default.\n- Updated to use openapi v1.0.\n- Changed default max-chars to 40000.\n\n### v0.7 | 2023-05-23\n- Added Code Interpretation, -x option.\n\n### v0.6 | 2023-05-11\n- Added all the settings as command-line arguments.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffedenunez%2Ftulp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffedenunez%2Ftulp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffedenunez%2Ftulp/lists"}