{"id":25000658,"url":"https://github.com/iehgit/parrotflume","last_synced_at":"2025-04-12T08:52:30.470Z","repository":{"id":271995068,"uuid":"915210654","full_name":"iehgit/parrotflume","owner":"iehgit","description":"Process data from a pipe or file with an OpenAI-compatible API, or chat with it on a CLI.","archived":false,"fork":false,"pushed_at":"2025-02-03T17:59:25.000Z","size":234,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T08:52:23.297Z","etag":null,"topics":["chatbot","cli","llm","nlp","openai-api","python"],"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/iehgit.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":"2025-01-11T08:55:05.000Z","updated_at":"2025-02-03T17:59:29.000Z","dependencies_parsed_at":"2025-02-03T18:38:40.726Z","dependency_job_id":"013c7d55-2288-44ce-bed5-6a81cad6e516","html_url":"https://github.com/iehgit/parrotflume","commit_stats":null,"previous_names":["iehgit/parrotflume"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iehgit%2Fparrotflume","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iehgit%2Fparrotflume/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iehgit%2Fparrotflume/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iehgit%2Fparrotflume/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iehgit","download_url":"https://codeload.github.com/iehgit/parrotflume/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248543883,"owners_count":21121838,"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":["chatbot","cli","llm","nlp","openai-api","python"],"created_at":"2025-02-04T19:36:30.093Z","updated_at":"2025-04-12T08:52:30.445Z","avatar_url":"https://github.com/iehgit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ParrotFlume\n\n**ParrotFlume** is a versatile command-line tool for using pipes (flumes) with LLMs (stochastic parrots[¹](https://dl.acm.org/doi/10.1145/3442188.3445922)), through OpenAI-compatible APIs. It also comes with a neat interactive chat CLI. Feed it through stdin, files, or keyboard input. Use it for scripting, single tasks or idle chitchat.\n\n## Operation Modes\n\n- **Transform Mode**: Transform data from stdin or file content based on a given instruction.\n- **Perform Mode**: Prompt the LLM about data from stdin or file content.\n- **Interactive Chat Mode**: Engage in a conversation with the LLM.\n- **One-Shot Mode**: Provide a single prompt and receive an immediate, complete response from the LLM.\n\n## Chat features\n- **Model switching**: Seamlessly switch between API providers and models during a conversation. Ask a second model to verify the reply of the first. Then ask a third who of the previous two was right.\n- **Markdown, LaTeX, and Color Support**: Enhanced output formatting with ANSI escape sequences and LaTeX to Unicode replacement.\n- **Function Calling**: Let the LLM evaluate mathematical expressions, solve equations, and more using built-in functions.\n- **Auto-Completion**: Enjoy tab-completion for API providers, models, and file paths when using commands in the interactive chat interface.\n\n![screenshot](screenshot.png)\n\n## Installation\n### From Git\nTo install ParrotFlume, clone the repository and install the package alongside its required dependencies:\n\n```bash\ngit clone https://github.com/iehgit/parrotflume.git\ncd parrotflume\npip install .\n```\n### From PyPi\nTo install ParrotFlume directly from [PyPi](https://pypi.org/project/parrotflume/), alongside its dependencies: \n```bash\npip install parrotflume\n```\n### Building a .deb\nIt is also possible to build and install it as a debian package:\n```bash\ngit clone https://github.com/iehgit/parrotflume.git\ncd parrotflume\ndpkg-buildpackage -us -uc\n# dpkg -i ../parrotflume_*.*.*_all.deb\n```\n\n## Configuration\n\nParrotFlume uses a TOML configuration file to manage API providers, model settings, and global options.\nAsk `parrotflume --help` about the place to put it for your operating system.  \nFor example, in Linux, the file should be placed there:\n```\n~/.config/parrotflume/parrotflume.config.toml\n```\nThe configuration file is optional if all needed parameters (url, key, model) are provided otherwise.\n\n### Example Configuration (`parrotflume.config.toml`)\n\n```toml\n# Example TOML configuration file for parrotflume\n\n[global_options]\ntemperature = 0.1     # Default temperature for the model\nmax_tokens = 4096     # Maximum number of tokens to generate\nmarkdown = true       # Enable markdown rendering\nlatex = true          # Enable LaTeX replacement\ncolor = true          # Enable colored output\ncolor_name = \"green\"  # ANSI name for colored output\n\n# API providers, the first in the list is used as default\n[[api_providers]]\nname = \"openai\"\nbase_url = \"https://api.openai.com/v1/\"\napi_key = \"\u003cyourapikeyhere\u003e\"\nmodel = \"gpt-4o\"\nfunc = true  # Enable function calling\n\n[[api_providers]]\nname = \"deepseek\"\nbase_url = \"https://api.deepseek.com/v1/\"\napi_key = \"\u003cyourapikeyhere\u003e\"\nmodel = \"deepseek-chat\"\nfunc = true  # Enable function calling\n\n[[api_providers]]\nname = \"llama.cpp\"\nbase_url = \"http://localhost:8080/v1/\"\napi_key = \"sk-no-key-required\"  # not used, NOT allowed to be empty for llama.cpp\nmodel = \"\"   # not used, allowed to be empty for llama.cpp\nfunc = true  # Enable function calling\n\n[[api_providers]]\nname = \"openrouter\"\nbase_url = \"https://openrouter.ai/api/v1/\"\napi_key = \"\u003cyourapikeyhere\u003e\"\nmodel = \"anthropic/claude-3.5-sonnet:beta\"\nfunc = true  # Enable function calling\n```\n\n## Usage\n\nCommand line parameters supersede environment variables. Environment variables supersede configuration file settings.\n\n### Command-Line Parameters\n\n#### General Parameters\n- **`--chat`**: Start an interactive chat session with the LLM.\n- **`--oneshot \"\u003cprompt\u003e\"`**: Provide a single prompt and get an immediate response. Example:\n  ```bash\n  parrotflume --oneshot \"What is the meaning of life, the universe, and everything?\"\n  ```\n- **`--transform \"\u003cprompt\u003e\" [filename]`**: Transform the content of a file using a prompt. If no filename is provided, reads from `stdin`. Examples:\n  ```bash\n  parrotflume --transform \"Convert all strings to uppercase\" input.txt \n  ```\n  ```bash\n  parrotflume --transform \"Fix all syntax errors\" \u003c input.txt \u003e output.txt\n  ```\n- **`--perform \"\u003cprompt\u003e\" [filename]`**: Perform a task on the content of a file. If no filename is provided, reads from `stdin`. Examples:\n  ```bash\n  parrotflume --perform \"Extract all email addresses\" input.txt \u003e emails.txt\n  ```\n  ```bash\n  dmesg | parrotflume --perform \"Explain all ACPI errors\" \n  ```\n- **`--list`**: List all available models from the configured API provider. Example:\n  ```bash\n  parrotflume --list\n  ```\n\n#### API Configuration Parameters\n- **`--api-provider \u003cprovider\u003e`**: Set the API provider (e.g., `openai`, `deepseek`, `llama.cpp`). Example:\n  ```bash\n  parrotflume --api-provider openai --chat\n  ```\n- **`--base-url \u003curl\u003e`**: Set the base URL for the API provider. Example:\n  ```bash\n  parrotflume --base-url \"https://api.openai.com/v1/\" --chat\n  ```\n- **`--key \u003ckey\u003e`**: Set the API key for the API provider. Example:\n  ```bash\n  parrotflume --key \"your-api-key-here\" --chat\n  ```\n- **`--model \u003cmodel\u003e`**: Set the model to use (e.g., `gpt-4o`, `deepseek-chat`). Example:\n  ```bash\n  parrotflume --model gpt-4o --chat\n  ```\n\n#### Model Behavior Parameters\n- **`--max-tokens \u003cmax\u003e`**: Set the maximum number of tokens to generate. Example:\n  ```bash\n  parrotflume --max-tokens 2048 --chat\n  ```\n- **`--warmth \u003ctemperature\u003e`**: Set the temperature for the model. Example:\n  ```bash\n  parrotflume --warmth 0.7 --chat\n  ```\n\n#### Output Formatting Parameters\nThese apply to chat and one-shot modes.\n\n- **`--markdown`**: Enable Markdown rendering in the output.\n- **`--no-markdown`**: Disable Markdown rendering in the output.\n- **`--color`**: Enable colored output.\n- **`--no-color`**: Disable colored output.\n- **`--latex`**: Enable LaTeX replacement in the output.\n- **`--no-latex`**: Disable LaTeX replacement in the output. \n\n#### Function Calling Parameters\n\n- **`--func`**: Enable function calling.\n- **`--no-func`**: Disable function calling.\n\nThis provides the LLM with some mathematical tools, the current date, and a way to sift through text using regex.  \nThe function calling feature requires support from both the API provider and the LLM.\n\nHint: Up-to-date llama.cpp supports function calling if it gets invoked with `--jinja`.\n\n#### JSON Parameter\n\n- **`--json`**: Enforces JSON output\n\n### Environment Variable\n\nYou can set the `OPENAI_API_KEY` environment variable to avoid passing your API key in a command line where it might be logged:\n\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\nThis will override any API key specified in the configuration file.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.\n\n## License\n\nParrotFlume is licensed under an extended MIT License. See the [LICENSE](LICENSE) file for more details.\n\n## Acknowledgments\n\n- The name \"ParrotFlume\" is inspired by the exhaustion of all slightly less silly names by different projects, and the title of a paper called \"On the Dangers of Stochastic Parrots: Can Language Models Be Too Big? 🦜\"[¹](https://dl.acm.org/doi/10.1145/3442188.3445922).\n- Special thanks to the developers of [llama.cpp](https://github.com/ggerganov/llama.cpp), which works nicely as a backend for ParrotFlume.\n\n## FAQ\n\n### Is it dead?\n\nNo no he's not dead, he's, he's restin'! Remarkable bird, the Norwegian Blue, idn'it, ay? Beautiful plumage!\n\n---\n\nEnjoy using ParrotFlume! For any questions or issues, please refer to the [GitHub issues page](https://github.com/iehgit/parrotflume/issues).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiehgit%2Fparrotflume","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiehgit%2Fparrotflume","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiehgit%2Fparrotflume/lists"}