{"id":26466747,"url":"https://github.com/quantalogic/qllm","last_synced_at":"2025-06-16T00:03:15.396Z","repository":{"id":246679396,"uuid":"821832618","full_name":"quantalogic/qllm","owner":"quantalogic","description":"QLLM: A powerful CLI for seamless interaction with multiple Large Language Models. Simplify AI workflows, streamline development, and unlock the potential of cutting-edge language models.  ⭐ If you find QLLM useful, consider giving us a star on GitHub! It helps us reach more developers and improve the tool. ⭐","archived":false,"fork":false,"pushed_at":"2025-04-09T14:20:49.000Z","size":2593,"stargazers_count":33,"open_issues_count":2,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T20:13:12.309Z","etag":null,"topics":["ai","cli","llm"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/quantalogic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-29T15:03:52.000Z","updated_at":"2025-04-09T14:20:52.000Z","dependencies_parsed_at":"2024-07-25T13:29:21.430Z","dependency_job_id":"0ab9d87b-e14a-4b00-ad45-33c70c3100a8","html_url":"https://github.com/quantalogic/qllm","commit_stats":null,"previous_names":["raphaelmansuy/qllm","quantalogic/qllm"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantalogic%2Fqllm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantalogic%2Fqllm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantalogic%2Fqllm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantalogic%2Fqllm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quantalogic","download_url":"https://codeload.github.com/quantalogic/qllm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103872,"owners_count":21048245,"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","cli","llm"],"created_at":"2025-03-19T12:38:02.356Z","updated_at":"2025-04-09T20:13:26.845Z","avatar_url":"https://github.com/quantalogic.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QLLM: Simplifying Language Model Interactions\n\n\n![npm version](https://img.shields.io/npm/v/qllm)\n![Stars](https://img.shields.io/github/stars/quantalogic/qllm)\n![Forks](https://img.shields.io/github/forks/quantalogic/qllm)\n![Downloads](https://img.shields.io/npm/dw/qllm)\n\n\n\n## Chapter 1: Introduction\n\n### 1.1 Welcome to QLLM\nWelcome to QLLM, your ultimate command-line tool for interacting with Large Language Models (LLMs). \n\n\u003e Imagine having a powerful AI assistant at your fingertips, ready to help you tackle complex tasks, generate creative content, and analyze data—all from your terminal. \n\nThis README will guide you through everything you need to know to harness the full potential of QLLM and become a master of AI-powered productivity.\n\n### 1.2 Show Your Support\nIf you find QLLM helpful and enjoyable to use, please consider giving us a star ✨ on GitHub! Your support not only motivates us to keep improving the project but also helps others discover QLLM. Thank you for being a part of our community!\n\n\n## Chapter 2: Benefits of QLLM\n\n### 2.1 Why QLLM and QLLM-LIB?\n#### Key Benefits:\n1. **Unified Access**: QLLM brings together multiple LLM providers under one roof. No more context-switching between different tools and APIs.  \n2. **Command-Line Power**: As a developer, you live in the terminal. QLLM integrates seamlessly into your existing workflow.  \n3. **Flexibility and Customization**: Tailor AI interactions to your specific needs with extensive configuration options and support for custom templates.  \n4. **Time-Saving Features**: From quick queries to ongoing conversations, QLLM helps you get answers fast.  \n5. **Cross-Platform Compatibility**: Works consistently across Windows, macOS, and Linux.  \n\n### 2.2 Anecdote: A Productivity Boost\nImagine you're a data analyst working on a tight deadline. You need to quickly analyze a large dataset and generate a report for your team. Instead of manually sifting through the data and writing the report, you turn to QLLM. With a few simple commands, you're able to:\n1. **Summarize the key insights** from the dataset.  \n2. **Generate visualizations** to highlight important trends.  \n3. **Draft a concise, well-written report**.  \n\nAll of this without leaving your terminal. The time you save allows you to focus on higher-level analysis and deliver the report ahead of schedule. Your manager is impressed, and you've just demonstrated the power of QLLM to streamline your workflow.\n\n## Chapter 3: Packages\n\n```mermaid\ngraph TD\n    A[qllm-cli] --\u003e B[qllm-lib]\n```\n\n\n\n### 3.1 qllm-lib\nA versatile TypeScript library for seamless LLM integration. It simplifies working with different AI models and provides features like templating, streaming, and conversation management.\n\n#### Practical Example\n```typescript\nimport { createLLMProvider } from 'qllm-lib';\n\nasync function generateProductDescription() {\n    const provider = createLLMProvider({ name: 'openai' });\n    const result = await provider.generateChatCompletion({\n        messages: [\n            {\n                role: 'user',\n                content: {\n                    type: 'text',\n                    text: 'Write a compelling product description for a new smartphone with a foldable screen, 5G capability, and 48-hour battery life.'\n                },\n            },\n        ],\n        options: { model: 'gpt-4', maxTokens: 200 },\n    });\n    console.log('Generated Product Description:', result.text);\n}\n\ngenerateProductDescription();\n```\n\n### 3.2 qllm-cli\nA command-line interface that leverages qllm-lib to provide easy access to LLM capabilities directly from your terminal.\n\n#### Practical Example\n```bash\n# Generate a product description\nqllm ask \"Write a 50-word product description for a smart home security camera with night vision and two-way audio.\"\n\n# Use a specific model for market analysis\nqllm ask --model gpt-4o-mini --provider openai \"Analyze the potential market impact of electric vehicles in the next 5 years. Provide 3 key points.\"\n\n# Write a short blog post about the benefits of remote work\nqllm ask --model gemma2:2b --provider ollama \"Write a short blog post about the benefits of remote work.\"\n\n# Analyze CSV data from stdin\ncat sales_data.csv | qllm ask \"Analyze this CSV data. Provide a summary of total sales, top-selling products, and any notable trends. Format your response as a bulleted list.\"\n\n## Example using question from stdin\necho \"What is the weather in Tokyo?\" | qllm  --provider ollama --model gemma2:2b \n```\n\n## Chapter 4: Getting Started\n\n### 4.1 System Requirements\nBefore we dive into the exciting world of QLLM, let's make sure your system is ready:\n- Node.js (version 16.5 or higher)\n- npm (usually comes with Node.js)\n- A terminal or command prompt\n- An internet connection (QLLM needs to talk to the AI, after all!)\n\n### 4.2 Step-by-Step Installation Guide\n1. Open your terminal or command prompt.\n2. Run the following command:\n   ```bash\n   npm install -g qllm\n   ```\n   This command tells npm to install QLLM globally on your system, making it available from any directory.\n3. Wait for the installation to complete. You might see a progress bar and some text scrolling by. Don't panic, that's normal!\n4. Once it's done, verify the installation by running:\n   ```bash\n   qllm --version\n   ```\n   You should see a version number (e.g., 1.8.0) displayed. If you do, congratulations! You've successfully installed QLLM.\n\n\u003e 💡 Pro Tip: If you encounter any permission errors during installation, you might need to use `sudo` on Unix-based systems or run your command prompt as an administrator on Windows.\n\n### 4.3 Configuration\nNow that QLLM is installed, let's get it configured. Think of this as teaching QLLM your preferences and giving it the keys to the AI kingdom.\n\n#### Configuring Default Settings\nWhile you're in the configuration mode, you can also set up some default preferences:\n1. Choose your default provider and model.\n2. Set default values for parameters like temperature and max tokens.\n3. Configure other settings like log level and custom prompt directory.\n\nHere's an example of what this might look like:\n```bash\n$ qllm configure\n? Default Provider: openai\n? Default Model: gpt-4o-mini\n? Temperature (0.0 to 1.0): 0.7\n? Max Tokens: 150\n? Log Level: info\n```\n\n#### AWS Configuration\nTo use AWS Bedrock with QLLM, you need to configure your AWS credentials. Ensure you have the following environment variables set:\n- `AWS_ACCESS_KEY_ID`: Your AWS access key ID.\n- `AWS_SECRET_ACCESS_KEY`: Your AWS secret access key.\n- `AWS_BEDROCK_REGION`: The AWS region you want to use (optional, defaults to a predefined region).\n- `AWS_BEDROCK_PROFILE`: If you prefer to use a named profile from your AWS credentials file, set this variable instead of the access key and secret.\n\nYou can set these variables in your terminal or include them in your environment configuration file (e.g., `.env` file) for convenience.\n\n\u003e 💡 Pro Tip: You can always change these settings later, either through the `qllm configure` command or directly in the configuration file located at `~/.qllmrc`.\n\u003e\n\n**Providers Supported**\n\n- openai\n- anthropic\n- AWS Bedrock (Anthropic)\n- ollama\n- groq\n- mistral\n- claude\n- openrouter\n\n### 4.4 Your First QLLM Command\nEnough setup, let's see QLLM in action! We'll start with a simple query to test the waters.\n\n#### Running a Simple Query\n1. In your terminal, type:\n   ```bash\n   qllm ask \"What is the meaning of life, the universe, and everything?\"\n   ```\n2. Press Enter and watch the magic happen!\n\n#### Understanding the Output\nQLLM will display the response from the AI. It might look something like this:\n```plaintext\nAssistant: The phrase \"the meaning of life, the universe, and everything\" is a reference to Douglas Adams' science fiction series \"The Hitchhiker's Guide to the Galaxy.\" In the story, a supercomputer named Deep Thought is asked to calculate the answer to the \"Ultimate Question of Life, the Universe, and Everything.\" After 7.5 million years of computation, it provides the answer: 42...\n```\n\n\u003e 🧠 **Pause and Reflect**: What do you think about this response? How does it compare to what you might have gotten from a simple web search?\n\n## Chapter 5: Core Commands\n\n### 5.1 The 'ask' Command\nThe `ask` command is your go-to for quick, one-off questions. It's like having a knowledgeable assistant always ready to help.\n\n#### Syntax and Options\n```bash\nqllm ask \"Your question here\"\n```\n- `-p, --provider`: Specify the LLM provider (e.g., openai, anthropic)\n- `-m, --model`: Choose a specific model\n- `-t, --max-tokens`: Set maximum tokens for the response\n- `--temperature`: Adjust output randomness (0.0 to 1.0)\n\n#### Use Cases and Examples\n1. Quick fact-checking:\n   ```bash\n   qllm ask \"What year was the first Moon landing?\"\n   ```\n2. Code explanation:\n   ```bash\n   qllm ask \"Explain this Python code: print([x for x in range(10) if x % 2 == 0])\"\n   ```\n3. Language translation:\n   ```bash\n   qllm ask \"Translate 'Hello, world!' to French, Spanish, and Japanese\"\n   ```\n\n### 5.2 The 'chat' Command\nWhile `ask` is perfect for quick queries, `chat` is where QLLM really shines. It allows you to have multi-turn conversations, maintaining context throughout.\n\n#### Starting and Managing Conversations\nTo start a chat session:\n```bash\nqllm chat\n```\nOnce in a chat session, you can use various commands:\n- `/help`: Display available commands\n- `/new`: Start a new conversation\n- `/save`: Save the current conversation\n\n### 5.3 The 'run' Command\nThe `run` command allows you to execute predefined templates, streamlining complex or repetitive tasks.\n\n#### Using Predefined Templates\nTo run a template:\n```bash\nqllm \u003ctemplate-url or path\u003e\n```\nFor example:\n```bash\nqllm  https://raw.githubusercontent.com/quantalogic/qllm/main/prompts/chain_of_thought_leader.yaml\n```\n\n#### Creating Custom Templates\nYou can create your own templates as YAML files. Here's a simple example:\n```yaml\nname: \"Simple Greeting\"\nversion: \"1.0\"\nauthor: \"Raphaël MANSUY\"\ndescription: \"A template that generates a greeting\"\ninput_variables:\n  name:\n    type: \"string\"\n    description: \"The name of the person to greet\"\ncontent: \u003e \"Generate a friendly greeting for {{name}}.\"\n```\nSave this as `greeting.yaml` and run it with:\n```bash\nqllm run greeting.yaml\n```\n\n\u003e 🧠 **Pause and Reflect**: How could you use custom templates to streamline your workflow? Think about repetitive tasks in your daily work that could benefit from AI assistance.\n\n## Chapter 6: Practical Examples\n\n### 6.1 Code Analysis Workflow\nImagine you're a developer facing code reviews. Let's set up a code review template to streamline this process.\n\n#### Setting up a Code Review Template\nSave this as `code_review.yaml`:\n```yaml\nname: \"Code Review\"\ndescription: \"Analyzes code and provides improvement suggestions\"\ninput_variables:\n  code:\n    type: \"string\"\n    description: \"The code to review\"\n  language:\n    type: \"string\"\n    description: \"The programming language\"\nprompt: \u003e\n  You are an experienced software developer. Review the following {{language}} code and provide suggestions for improvement: {{language}} {{code}}\n  Please consider:\n  1. Code efficiency\n  2. Readability\n  3. Best practices\n  4. Potential bugs\n```\n\n### 6.2 Content Creation Pipeline\nLet's look at how QLLM can assist in content creation, from ideation to drafting and editing.\n\n#### Ideation Phase\nCreate a template for brainstorming ideas. Save this as `brainstorm_ideas.yaml`:\n```yaml\nname: \"Content Brainstorming\"\ndescription: \"Generates content ideas based on a topic and target audience\"\ninput_variables:\n  topic:\n    type: \"string\"\n    description: \"The main topic or theme\"\n  audience:\n    type: \"string\"\n    description: \"The target audience\"\n  content_type:\n    type: \"string\"\n    description: \"The type of content (e.g., blog post, video script, social media)\"\nprompt: |\n  As a creative content strategist, generate 5 unique content ideas for {{content_type}} about {{topic}} targeted at {{audience}}. For each idea, provide:\n  1. A catchy title\n  2. A brief description (2-3 sentences)\n  3. Key points to cover\n  4. Potential challenges or considerations\n```\n\n### 6.3 Data Analysis Assistant\nImagine you have a CSV file with sales data. You can use QLLM to help interpret this data:\n```bash\ncat sales_data.csv | qllm ask \"Analyze this CSV data. Provide a summary of total sales, top-selling products, and any notable trends. Format your response as a bulleted list.\"\n```\n\n### 6.4 Image Analysis and Description\nQLLM also supports image analysis, allowing you to describe and analyze images directly through the command line.\n\n#### Example of Image Analysis\n```bash\nqllm ask \"What do you see in this image?\" -i path/to/image.jpg\n```\nThis command sends the specified image to the AI for analysis and generates a description based on its contents.\n\n### 6.5 Screenshots Feature\nYou can capture and analyze screenshots directly from the CLI, making it easier to get insights from visual content.\n\n#### Example of Using Screenshots\n```bash\nqllm ask \"Analyze this screenshot\" --screenshot 0\n```\nThis command captures the current screen and sends it to the AI for analysis, providing insights based on what is displayed.\n\n## Chapter 7: Troubleshooting Common Issues\nEven the most powerful tools can sometimes hiccup. Here are some common issues you might encounter with QLLM and how to resolve them:\n1. **Rate Limiting**: Implement a retry mechanism with exponential backoff.\n2. **Unexpected Output Format**: Be more specific in your prompts.\n\n## Chapter 8: Best Practices\nTo get the most out of QLLM, keep these best practices in mind:\n1. **Effective Prompt Engineering**: Be specific and clear in your prompts.\n2. **Managing Conversation Context**: Use `/new` to start fresh conversations when switching topics.\n3. **Leveraging Templates for Consistency**: Create templates for tasks you perform regularly.\n\n## Chapter 9: Conclusion and Next Steps\nCongratulations! You've now mastered the essentials of QLLM and are well on your way to becoming a CLI AI wizard.\n\n### 9.1 Final Challenge\nWithin the next 24 hours, use QLLM to solve a real problem you're facing in your work or personal projects. It could be analyzing some data, drafting a document, or even helping debug a tricky piece of code. Share your experience with a colleague or in the QLLM community.\n\nThank you for joining me on this whirlwind tour of QLLM. Now go forth and command your AI assistant with confidence! 🚀\n\n## Chapter 10: Additional Resources\nFor detailed documentation on the packages used in QLLM, please refer to the following links:\n\n## 10. Contributing\n\nWe warmly welcome contributions to QLLM CLI! This project is licensed under the Apache License, Version 2.0. To contribute, please follow these steps:\n\n1. Fork the repository on GitHub.\n2. Clone your forked repository to your local machine.\n3. Create a new branch for your feature or bug fix.\n4. Make your changes, adhering to the existing code style and conventions.\n5. Write tests for your changes if applicable.\n6. Run the existing test suite to ensure your changes don't introduce regressions:\n    ```\n    pnpm test\n    ```\n7. Commit your changes with a clear and descriptive commit message.\n8. Push your changes to your fork on GitHub.\n9. Create a pull request from your fork to the main QLLM CLI repository.\n\nPlease ensure your code adheres to our coding standards:\n\n-   Use TypeScript for type safety.\n-   Follow the existing code style (we use Prettier for formatting).\n-   Write unit tests for new features.\n-   Update documentation as necessary, including this README if you're adding or changing features.\n\nWe use GitHub Actions for CI/CD, so make sure your changes pass all automated checks.\n\n### License\n\nThis project is licensed under the Apache License, Version 2.0. You may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n\n## Project Growth\n[![Star History Chart](https://api.star-history.com/svg?repos=quantalogic/qllm\u0026type=Date)](https://star-history.com/#quantalogic/qllm\u0026Date)\n\n## Acknowledgements\n\nWe would like to extend our heartfelt thanks to the following individuals and organizations for their invaluable contributions to QLLM:\n\n1. **OpenAI**: For their groundbreaking work on large language models and the API that powers QLLM.\n2. **Anthropic**: For their innovative approach to AI and the Claude models that enhance QLLM's capabilities.\n3. **AWS Bedrock**: For their support in providing access to advanced AI models through AWS.\n4. **Ollama**: For their cutting-edge LLM platform that powers QLLM's locally.\n5. **Groq**: For their powerful and scalable LLM infrastructure.\n6. **Mistral**: For their innovative approach to AI and te represent France 🇫🇷.\n\n\nA special thanks to the entire QLLM community for their feedback and support. Your insights and contributions are invaluable to us.\n\nAnd of course for Quantalogic for funding the project.\n\nhttps://www.quantalogic.app \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantalogic%2Fqllm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquantalogic%2Fqllm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantalogic%2Fqllm/lists"}