q-bot 1.4.0__tar.gz → 2.0.0.dev1__tar.gz

q_bot-2.0.0.dev1/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: q-bot
+Version: 2.0.0.dev1
+Summary: An LLM agent from the comfort of your command line
+Author-email: Tushar Khan <dev@tusharkhan.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/tk755/q
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic==0.75.0
+Requires-Dist: colorama==0.4.6
+Requires-Dist: distro==1.9.0
+Requires-Dist: humanize==4.14.0
+Requires-Dist: openai==2.9.0
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: pyperclip==1.11.0
+Requires-Dist: python-dotenv==1.2.1
+Requires-Dist: termcolor==3.2.0
+
+# Overview
+
+`q` is a lightweight, flexible, multi-provider LLM-agent framework for the terminal. 
+
+I built this before Claude Code ever existed, and it remains useful to me for quick CLI interactions or prototyping multi-agent experiments. However, for most complex coding tasks, Claude Code is unquestionably superior.
+
+# Installation
+
+Install using any pip-compatible package manager (e.g. `pip`, `pipx`, `uv`, etc.):
+
+```bash
+pipx install q-bot
+```
+
+Requires Python 3.12+.
+
+# CLI Usage
+
+`q` uses a simple paradigm where each character from a-z is mapped to a single flag representing a command or option. This enables concise combinations of flags to achieve complex behavior.
+
+## Flag Reference
+
+| Flag | Name         | Arg     | Description                    | Type    |
+| ---- | ------------ | ------- | ------------------------------ | ------: |
+| `-a` | agent        |         | *[reserved for future use]*    | Command |
+| `-b` | batch        |         | *[reserved for future use]*    |         |
+| `-c` | code         | str     | generate code                  | Command |
+| `-d` | directory    | - / str | add a directory to context     | Option  |
+| `-e` | explain      | - / str | explain code or text           | Command |
+| `-f` | file         | str     | read input from file           | Option  |
+| `-g` |              |         |                                |         |
+| `-h` | help         | - / str | help message / help agent      | Command |
+| `-i` | image        | str     | generate/edit an image         | Command |
+| `-j` | json         | -       | output as JSON                 | Option  |
+| `-k` | api key      | str     | *[reserved for future use]*    | Option  |
+| `-l` | load         | - / int | list all / load session by id  | Command |
+| `-m` | model        | str     | set model and/or provider      | Option  |
+| `-n` |              |         |                                |         |
+| `-o` | output       | str     | output file                    | Option  |
+| `-p` |              |         |                                |         |
+| `-q` |              |         |                                |         |
+| `-r` | rag          | - / str | *[reserved for future use]*    | Command |
+| `-s` | shell        | - / str | generate a shell command       | Command |
+| `-t` | text         | str     | generate text                  | Command |
+| `-u` | user command | str     | *[reserved for future use]*    | Command |
+| `-v` | verbose      | -       | debug logging                  | Option  |
+| `-w` | web search   | str     | search the web                 | Command |
+| `-x` | execute      | -       | execute a shell command        | Option  |
+| `-y` |              |         |                                |         |
+| `-z` | undo         | - / int | undo exchanges (default 1)     | Option  |
+
+<!-- [TODO]
+
+# Library Usage
+
+`q` follows a highly modular and provider-agnostic capability-driven design. -->

q_bot-2.0.0.dev1/README.md

@@ -0,0 +1,56 @@
+# Overview
+
+`q` is a lightweight, flexible, multi-provider LLM-agent framework for the terminal. 
+
+I built this before Claude Code ever existed, and it remains useful to me for quick CLI interactions or prototyping multi-agent experiments. However, for most complex coding tasks, Claude Code is unquestionably superior.
+
+# Installation
+
+Install using any pip-compatible package manager (e.g. `pip`, `pipx`, `uv`, etc.):
+
+```bash
+pipx install q-bot
+```
+
+Requires Python 3.12+.
+
+# CLI Usage
+
+`q` uses a simple paradigm where each character from a-z is mapped to a single flag representing a command or option. This enables concise combinations of flags to achieve complex behavior.
+
+## Flag Reference
+
+| Flag | Name         | Arg     | Description                    | Type    |
+| ---- | ------------ | ------- | ------------------------------ | ------: |
+| `-a` | agent        |         | *[reserved for future use]*    | Command |
+| `-b` | batch        |         | *[reserved for future use]*    |         |
+| `-c` | code         | str     | generate code                  | Command |
+| `-d` | directory    | - / str | add a directory to context     | Option  |
+| `-e` | explain      | - / str | explain code or text           | Command |
+| `-f` | file         | str     | read input from file           | Option  |
+| `-g` |              |         |                                |         |
+| `-h` | help         | - / str | help message / help agent      | Command |
+| `-i` | image        | str     | generate/edit an image         | Command |
+| `-j` | json         | -       | output as JSON                 | Option  |
+| `-k` | api key      | str     | *[reserved for future use]*    | Option  |
+| `-l` | load         | - / int | list all / load session by id  | Command |
+| `-m` | model        | str     | set model and/or provider      | Option  |
+| `-n` |              |         |                                |         |
+| `-o` | output       | str     | output file                    | Option  |
+| `-p` |              |         |                                |         |
+| `-q` |              |         |                                |         |
+| `-r` | rag          | - / str | *[reserved for future use]*    | Command |
+| `-s` | shell        | - / str | generate a shell command       | Command |
+| `-t` | text         | str     | generate text                  | Command |
+| `-u` | user command | str     | *[reserved for future use]*    | Command |
+| `-v` | verbose      | -       | debug logging                  | Option  |
+| `-w` | web search   | str     | search the web                 | Command |
+| `-x` | execute      | -       | execute a shell command        | Option  |
+| `-y` |              |         |                                |         |
+| `-z` | undo         | - / int | undo exchanges (default 1)     | Option  |
+
+<!-- [TODO]
+
+# Library Usage
+
+`q` follows a highly modular and provider-agnostic capability-driven design. -->

q_bot-2.0.0.dev1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "q-bot"
+dynamic = ["version"]
+description = "An LLM agent from the comfort of your command line"
+requires-python = ">=3.12"
+dependencies = [
+    "anthropic==0.75.0",
+    "colorama==0.4.6",
+    "distro==1.9.0",
+    "humanize==4.14.0",
+    "openai==2.9.0",
+    "pydantic==2.12.5",
+    "pyperclip==1.11.0",
+    "python-dotenv==1.2.1",
+    "termcolor==3.2.0",
+]
+authors = [
+    {name = "Tushar Khan", email = "dev@tusharkhan.com"}
+]
+readme = "README.md"
+license = "MIT"
+
+[project.scripts]
+q = "q.cli.main:main"
+
+[project.urls]
+Repository = "https://github.com/tk755/q"
+
+[tool.setuptools.packages.find]
+include = ["q*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "q.__version__"}

q_bot-2.0.0.dev1/q/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0.dev1"

q_bot-2.0.0.dev1/q/agents.py

@@ -0,0 +1,63 @@
+import asyncio
+
+from .client import Client
+from .message import Message, Role
+
+
+class ChatAgent[T]:
+    """Conversational agent with persistent message history."""
+
+    def __init__(self, client: Client[T], system: str | None = None, messages: list[Message] | None = None):
+        self.client = client
+        self.system = system
+        self.messages: list[Message] = messages.copy() if messages else []
+
+    async def prompt(self, text: str) -> T:
+        """Generate response and update conversation history."""
+        self.messages.append(Message(role=Role.USER, content=text))
+
+        messages = self.messages
+        if self.system:
+            messages = [Message(role=Role.SYSTEM, content=self.system), *self.messages]
+        response = await self.client.generate(messages)
+
+        if isinstance(response, str):
+            self.messages.append(Message(role=Role.ASSISTANT, content=response))
+
+        return response
+
+    def drop_exchanges(self, n: int = 1) -> None:
+        """Drop the last N conversation exchanges (user message + responses)."""
+        if n <= 0:
+            return
+
+        user_messages_found = 0
+        for i in range(len(self.messages) - 1, -1, -1):
+            if self.messages[i].role == Role.USER:
+                user_messages_found += 1
+                if user_messages_found == n:
+                    self.messages = self.messages[:i]
+                    return
+
+
+class BatchAgent[T]:
+    """Batch agent for applying a single prompt to multiple inputs concurrently."""
+
+    def __init__(self, client: Client[T], system: str | None = None):
+        self.client = client
+        self.system = system
+
+    async def batch_prompt(self, text_list: list[str], n_threads: int = 8) -> list[T]:
+        """Process multiple inputs concurrently and return the outputs in order."""
+        semaphore = asyncio.Semaphore(n_threads)
+
+        async def process(text: str) -> T:
+            async with semaphore:
+                messages: list[Message] = []
+                if self.system:
+                    messages.append(Message(role=Role.SYSTEM, content=self.system))
+                messages.append(Message(role=Role.USER, content=text))
+                return await self.client.generate(messages)
+
+        tasks = [process(text) for text in text_list]
+        return await asyncio.gather(*tasks)

q_bot-2.0.0.dev1/q/cli/commands.py

@@ -0,0 +1,434 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import platform
+import shutil
+import string
+import subprocess
+import sys
+from abc import ABC, abstractmethod
+from enum import Enum
+from pathlib import Path
+
+import distro
+import humanize
+import pyperclip
+from termcolor import colored
+
+from q import __version__
+from q.providers import load_client_class
+
+from ..agents import ChatAgent
+from ..message import Role
+from .models import Tier, resolve_model_arg
+from .session import SessionManager
+from .terminal import UserError, format_response, qprint
+
+# region Registry
+
+COMMANDS: list[type[Command]] = []
+OPTIONS: list[type[Flag]] = []
+
+
+def get_default_command() -> type[Command]:
+    char = SessionManager.load_command_char()
+    if char:
+        for cmd in COMMANDS:
+            if cmd.char == char:
+                return cmd
+    return TextCommand
+
+
+# region Types
+
+type Value = str | int | None
+type ArgMap = dict[str, Value]
+
+
+class ValueType(Enum):
+    NONE = None
+    TEXT = "text"
+    STR = "str"
+    INT = "N"
+
+
+# region Base Classes
+
+
+class Flag(ABC):
+    """Base class for CLI flags. Subclasses auto-register to OPTIONS."""
+
+    char: str
+    desc: str
+    value_type: ValueType = ValueType.NONE
+    required: bool = False
+    default: Value = None
+
+    def __init_subclass__(cls, **kwargs):
+        """Auto-register subclass to OPTIONS if it defines a char."""
+        super().__init_subclass__(**kwargs)
+        if hasattr(cls, "char"):
+            OPTIONS.append(cls)
+
+
+class Command(Flag):
+    """Base class for CLI commands. Subclasses auto-register to COMMANDS."""
+
+    def __init__(self, args: ArgMap):
+        self.args = args
+
+    def __init_subclass__(cls, **kwargs):
+        """Move subclass from OPTIONS to COMMANDS if it defines a char."""
+        super().__init_subclass__(**kwargs)
+        if hasattr(cls, "char"):
+            OPTIONS.remove(cls)
+            COMMANDS.append(cls)
+
+    @abstractmethod
+    async def execute(self) -> None: ...
+
+
+class AgentCommand(Command):
+    """Base class for commands that prompt an agent."""
+
+    client_str: str = "TextClient"
+    tier: Tier
+    system: str | None = None
+    clip: bool = False
+
+    async def execute(self) -> None:
+        if "n" in self.args:
+            SessionManager.new_session()
+
+        # resolve provider, model, and model args
+        default_provider = SessionManager.load_default_provider()
+        provider, model, model_args = resolve_model_arg(self.args.get("m"), self.tier, default_provider)
+
+        # create client dynamically
+        client_class = load_client_class(provider, self.client_str)
+        api_key = SessionManager.load_api_key(provider)
+        client = client_class(api_key, model, **model_args)
+
+        if "v" in self.args:
+            qprint("MODEL PARAMETERS:", color="cyan", file=sys.stderr)
+            qprint("model: ", color="green", file=sys.stderr, end="")
+            qprint(f"{client.model} ({provider})", file=sys.stderr)
+            if client.model_args:
+                for k, v in client.model_args.items():
+                    qprint(f"{k}: ", color="green", file=sys.stderr, end="")
+                    qprint(f"{v}", file=sys.stderr)
+
+        # resolve system prompt (command's system overrides saved system)
+        system = self.system if self.system is not None else SessionManager.load_system()
+
+        # create agent
+        agent = ChatAgent(client, system, SessionManager.load_messages())
+        if "z" in self.args:
+            agent.drop_exchanges(self.args["z"])
+
+        # prompt agent and save session
+        response = await agent.prompt(self.args[self.char])
+        SessionManager.save_session(agent.system, agent.messages, self.char)
+
+        if "v" in self.args:
+            qprint("\nMESSAGES:", color="cyan", file=sys.stderr)
+            if agent.system:
+                qprint("system: ", color="green", file=sys.stderr, end="")
+                qprint(agent.system, file=sys.stderr)
+            for msg in agent.messages:
+                qprint(f"{msg.role.value}: ", color="green", file=sys.stderr, end="")
+                qprint(msg.content, file=sys.stderr)
+
+        # process response
+        self.process_response(response)
+
+    def process_response(self, response: str) -> None:
+        """Format response and route output."""
+        if "j" not in self.args:
+            response = format_response(response)
+
+        if "o" in self.args:
+            Path(self.args["o"]).write_text(response)
+            qprint(f"Response saved to {self.args['o']}", color="yellow", file=sys.stderr)
+        else:
+            if "v" not in self.args:
+                qprint(response)
+            
+            # copy output to clipboard
+            if self.clip:
+                with contextlib.suppress(pyperclip.PyperclipException):
+                    pyperclip.copy(response)
+                    qprint("Copied to clipboard.", color="yellow", file=sys.stderr)
+
+
+# region Commands
+
+
+class TextCommand(AgentCommand):
+    char = "t"
+    desc = "text"
+    value_type = ValueType.TEXT
+    required = True
+    tier = Tier.MED
+    system = ""
+
+
+class ExplainCommand(AgentCommand):
+    char = "e"
+    desc = "explain"
+    value_type = ValueType.TEXT
+    tier = Tier.HIGH
+    system = "You are a programming assistant. Given a shell command, code snippet, or technical concept, provide a concise and technical explanation. Assume the reader is an experienced developer. Avoid restating the code or command. Avoid explaining obvious syntax. Avoid breaking the answer into bullet points unless necessary. The response should be a single short paragraph optimized for clarity."
+
+
+class CodeCommand(AgentCommand):
+    char = "c"
+    desc = "code"
+    value_type = ValueType.TEXT
+    required = True
+    tier = Tier.HIGH
+    clip = True
+
+    @property
+    def system(self) -> str:
+        return f"You are a coding assistant. Given a natural language description, generate a code snippet that accomplishes the requested task. The code should be correct, efficient, concise, and idiomatic. Respond with only the code snippet, without explanations, additional text, or formatting. Assume the programming language is {SessionManager.load_code_lang()} unless otherwise specified."
+
+
+class ShellCommand(AgentCommand):
+    char = "s"
+    desc = "shell"
+    value_type = ValueType.TEXT
+    required = False
+    tier = Tier.MED
+    clip = True
+
+    @property
+    def system(self) -> str:
+        return f"You are a command-line assistant. Given a description, generate the simplest single shell command that accomplishes the task. Favor minimal, commonly available commands with no extra formatting or piping. Avoid commands that could delete, overwrite, or modify important files or system settings (e.g., rm -rf, dd, mkfs, chmod -R, chown, kill -9). Respond with only the command, without explanations, additional text, or formatting. System is running {self._get_system_info()}."
+
+    def _get_system_info(self) -> str:
+        shell = os.environ.get("SHELL") or os.environ.get("COMSPEC")
+        shell = Path(shell).name if shell else ""
+
+        sys_name = platform.system()
+        if sys_name == "Linux":
+            with contextlib.suppress(ImportError):
+                sys_name = distro.name(pretty=True)
+
+        if shell:
+            return f"{shell} on {sys_name}"
+        return sys_name
+
+    async def execute(self) -> None:
+        # rerun and fix last command (requires shell integration)
+        if self.args[self.char] is None:
+            cmd = os.environ.get("Q_CMD", None)
+            exit_code = os.environ.get("Q_EXIT", None)
+            if cmd is None or exit_code is None:
+                raise UserError(
+                    "q -s without a prompt requires shell integration. Add to ~/.bashrc:\n"
+                    '    q() { Q_EXIT=$? Q_CMD=$(fc -ln -1) command q "$@"; }'
+                )
+            cmd, exit_code = cmd.strip(), exit_code.strip()
+
+            try:
+                # run command and capture output
+                proc = await asyncio.create_subprocess_shell(
+                    cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+                )
+                stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=10)
+                text = f"The command `{cmd}` failed with exit code {proc.returncode}. Fix it."
+                if stderr:
+                    text += f"\nSTDERR:\n{stderr.decode().strip()}"
+                if stdout:
+                    text += f"\nSTDOUT:\n{stdout.decode().strip()}"
+            except TimeoutError:
+                # kill long-running command
+                proc.kill()
+                text = f"The command `{cmd}` failed with exit code {exit_code}. Fix it."
+            self.args[self.char] = text
+
+        await super().execute()
+
+    def process_response(self, response: str) -> None:
+        # execute command
+        if "x" in self.args:
+            qprint(f"> {response}", color="green", file=sys.stderr)
+            subprocess.run(response, shell=True)
+        else:
+            super().process_response(response)
+
+
+class WebCommand(AgentCommand):
+    char = "w"
+    desc = "web"
+    value_type = ValueType.TEXT
+    required = True
+    tier = Tier.LOW
+    client_str = "WebClient"
+    system = "You fetch real-time data from the internet. Always respond with only the data requested. Do not provide additional information in the form of context, background, or links. The response should be less than a single sentence. Always search the internet."
+
+
+class ImageCommand(AgentCommand):
+    char = "i"
+    desc = "image"
+    value_type = ValueType.TEXT
+    required = True
+    tier = Tier.MED
+    client_str = "ImageClient"
+    system = "Generate an image of the following description."
+
+    def process_response(self, response: bytes) -> None:
+        text = self.args[self.char].translate(str.maketrans("", "", string.punctuation)).replace(" ", "_")
+        path = self.args.get("o") or f"q_{text}"
+        path = path if path.lower().endswith(".png") else f"{path}.png"
+        Path(path).write_bytes(response)
+        qprint(f"Image saved to {path}", color="yellow", file=sys.stderr)
+
+
+class HelpCommand(AgentCommand):
+    char = "h"
+    desc = "help"
+    value_type = ValueType.TEXT
+    required = False
+    tier = Tier.LOW
+
+    @property
+    def system(self) -> str:
+        cli_dir = Path(__file__).parent
+        source_code = "\n\n".join((cli_dir / name).read_text() for name in Path(cli_dir).glob("*.py"))
+        return (
+            "You are `q`, a command-line LLM tool. Answer questions about usage based on the source code."
+            f"\n\n{source_code}\n\n"
+            "Be extremely concise. Answer in one line. Focus on usage."
+            "Always surround code snippets, commands, flags, and paths with backticks."
+        )
+
+    async def execute(self) -> None:
+        if self.args.get(self.char):
+            await super().execute()
+        else:
+            qprint(self._help_text())
+
+    def _help_text(self) -> str:
+        command_color = "cyan"
+        flags = []
+        for f in sorted(COMMANDS + OPTIONS, key=lambda f: f.char):
+            flag_arg = f.value_type.value or ""
+            if flag_arg:
+                flag_arg = f"<{flag_arg}>" if f.required else f"[{flag_arg}]"
+            flag_str = f"    -{f.char}  {f.desc} {flag_arg}"
+            flags.append(colored(flag_str, command_color if f in COMMANDS else "dark_grey"))
+
+        lines = [
+            f"q {__version__} - a command line programming agent",
+            "",
+            "Usage: q [-flag [value]] ...",
+            "",
+            "  Flags can be combined: -sx = -s -x",
+            "  Use -- to disable remaining flag parsing.",
+            f"  One {colored('command', command_color)} is required.",
+            "",
+            "Flags:",
+            *flags,
+        ]
+        return "\n".join(lines)
+
+
+class LoadCommand(Command):
+    char = "l"
+    desc = "load session"
+    value_type = ValueType.INT
+
+    async def execute(self) -> None:
+        session_id = self.args.get(self.char)
+        if session_id is None:
+            self._print_session_list()
+        elif not SessionManager.switch_session(session_id):
+            raise UserError(f"invalid session: {session_id}")
+        else:
+            qprint(f"Loaded session {session_id}", color="yellow", file=sys.stderr)
+
+    def _print_session_list(self) -> None:
+        sessions = SessionManager.list_sessions()
+        if not sessions:
+            qprint("No sessions found.")
+            return
+
+        current_id = SessionManager.load_session_id()
+        term_width = shutil.get_terminal_size().columns
+
+        for s in sessions:
+            age = humanize.naturaltime(s.updated) if s.updated else "unknown"
+            prefix_len = len(f"    {s.id}.  ")
+            suffix_len = len(f" ({age})")
+            max_len = max(20, term_width - prefix_len - suffix_len - 5)
+
+            preview = "(empty)"
+            for msg in reversed(s.messages):
+                if msg.role == Role.USER:
+                    preview = msg.content[:max_len] + "..." if len(msg.content) > max_len else msg.content
+                    break
+
+            line = f"    {s.id}.  {preview} ({age})"
+            color = None if s.id == current_id else "dark_grey"
+            qprint(line, color=color)
+
+
+# region Options
+
+
+class DirectoryOption(Flag):
+    char = "d"
+    desc = "directory"
+    value_type = ValueType.STR
+
+
+class FileOption(Flag):
+    char = "f"
+    desc = "file"
+    value_type = ValueType.STR
+    required = True
+
+
+class JsonOption(Flag):
+    char = "j"
+    desc = "json"
+
+
+class ModelOption(Flag):
+    char = "m"
+    desc = "model"
+    value_type = ValueType.STR
+    required = True
+
+
+class NewSessionOption(Flag):
+    char = "n"
+    desc = "new session"
+
+
+class OutputOption(Flag):
+    char = "o"
+    desc = "output"
+    value_type = ValueType.STR
+    required = True
+
+
+class VerboseOption(Flag):
+    char = "v"
+    desc = "verbose"
+
+
+class ExecuteOption(Flag):
+    char = "x"
+    desc = "execute"
+
+
+class UndoOption(Flag):
+    char = "z"
+    desc = "undo"
+    value_type = ValueType.INT
+    default = 1

q_bot-2.0.0.dev1/q/cli/main.py

@@ -0,0 +1,26 @@
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+from .parser import parse
+from .terminal import UserError, is_terminal, qprint
+
+
+def main():
+    # suppress stderr when piped
+    if not is_terminal():
+        sys.stderr = Path(os.devnull).open("w") # noqa: SIM115
+
+    try:
+        command = parse(sys.argv[1:])
+        asyncio.run(command.execute())
+    except (UserError, ImportError) as e:
+        qprint(str(e), color="red", file=sys.stderr)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()