Package: roboduck
rubber duck debugging: a method of debugging code by articulating a problem in spoken or written natural language. The name is a reference to a story in the book The Pragmatic Programmer in which a programmer would carry around a rubber duck and debug their code by forcing themselves to explain it, line-by-line, to the duck. [1]robo duck debugging: a bit like rubber duck debugging, but the duck talks back.AboutHave you ever wanted to ask your program why it's not working?Many AI-powered dev tools help you write boilerplate more quickly, but the hardest and most time-consuming part of programming is often the last mile. Roboduck's goal is to help you understand and fix those bugs. It essentially embeds an LLM (large language model) in the Python interpreter, providing drop-in natural language replacements for Python's standard approaches to:debuggingerror handlingloggingQuickstartInstallpip install roboduckAPI Key SetupYou need an openai API key to begin using roboduck. Once you have an account (sign up here), you can visithttps://platform.openai.com/account/api-keysto retrieve your key. Your simplest option is then to callroboduck.set_openai_api_key(api_key, update_config_=True)which essentially does the following:mkdir~/.roboduckecho"openai_api_key: your_api_key">~/.roboduck/config.yamlManually setting an OPENAI_API_KEY environment variable also works.Roboduck does not store your API key or collect any usage data.DebuggerWe provide a natural language equivalent of python's built-inbreakpointfunction. Once you're in an interactive session, you can use the standard pdb commands to navigate your code (cmd+f "debugger commands"here. TLDR: typento execute the next line, a variable name to view its current value, orqto quit the debugging session). However, you can also type a question like "Why do we get an index error when j changes from 3 to 4?" or "Why does nums have three 9s in it when the input list only had one?". Concretely, any time you type something including a question mark, an LLM will try to answer. This is not just performing static analysis - the LLM can access information about the current state of your program.from roboduck import duck

def bubble_sort(nums):
    for i in range(len(nums)):
        for j in range(len(nums)):
            if nums[j] > nums[j + 1]:
                nums[j + 1] = nums[j]
                nums[j] = nums[j + 1]
                duck()   # <--------------------------- instead of breakpoint()
    return nums

nums = [3, 1, 9, 2, 1]
bubble_sort(nums)ErrorsRoboduck is also good at explaining error messages.  Importing the errors module automatically enablesoptionalerror explanations.errors.disable()reverts to python's regular behavior on errors.errors.enable()can be used to re-enable error explanations or to change settings. For example, setting auto=True automatically explains all errors rather than asking the user if they want an explanation (y/n) when an error occurs (this is probably excessive for most use cases, but you're free to do it).from roboduck import errors

data = {'x': 0}
y = data.x

errors.disable()
y = data.x

errors.enable(auto=True)
y = data.xJupyter MagicJupyter provides a%debugmagic that can be used after an error occurs to enter a postmortem debugging session. Roboduck's%duckmagic works similarly, but with all of our debugging module's conversational capabilities:# cell 1
from roboduck import magic

nums = [1, 2, 3]
nums.add(4)# cell 2
%duckLoggingRoboduck also provides a logger that can write to stdout and/or a file. Whenever you log an Exception object, an LLM will try to diagnose and suggest a fix for the problem. (Unlike the debug module, the logger does not type responses live because we assume logs will typically be viewed after the fact.)from roboduck import logging

logger = logging.getLogger(path='/tmp/log.txt')
data = {'x': 0}
try:
    x = data.x
except Exception as e:
    logger.error(e)CLIYou can also run a python script with error explanations enabled:duckmy_script.pyRunduck --helpfor more info.Usage AdviceLanguage models are not infallible. You should not blindly assume that roboduck's code snippets are flawless or that its explanations are a source of unimpeachable truth. But that's kind of the whole reason roboduck is useful - if LLMs were perfectly reliable, humans wouldn't need to write code at all. We could simply generate it,./deploy.sh, and call it a day. Maybe we'll get there eventually but in the meantime, I believe LLMs are best viewed as tools to augment human thought. It's ultimately still up to you to assess and make use of what they tell you.It comes back to the name of the library. Sure, as a pun it only kind of makes sense, but it's a good mental cue. Conversing with rubber ducks isn't an effective debugging strategy because bath toys are brilliant programmers - the practice just encourages you to hone in on what the problem is, what you understand and what you don't, what would need to be true for your program to function correctly. Roboduck obviously takes a more active role in the conversation, but that mindset is still useful.ContributingTo create a virtual environment and install relevant packages:make dev_envTo run unit tests:make testTo rebuild the docs locally:make docsStart of auto-generated file data.Last updated: 2023-06-02 21:08:08FileSummaryLine CountLast ModifiedSize__init__.py_172023-06-01 23:26:46548.00 bconfig.pyAllow us to easily read from and write to roboduck's config file.Roboduck creates a config file at `~/.roboduck/config.yaml`. This currentlysupports only two fields:- `openai_api_key`: See the [Quickstart](https://hdmamin.github.io/roboduck/)for setup help.- `model_name` (optional): Roboduck is configured to use gpt-3.5-turbo bydefault. This field lets you change that (e.g. to gpt-4). If present in theconfig file, this will take priority over any model_name field specified in achat template(e.g. our [default debug prompt template](https://github.com/hdmamin/roboduck/blob/7ff904972921fd3f82b8b9fd862c4ffc7b61aee4/lib/roboduck/prompts/chat/debug.yaml#L2)).You can view valid options with `roboduck.available_models()`.You can still override the config default by manually passing a value into afunction, e.g. `duck(model_name='gpt-4-32k')`.You can manually edit your config file or use a command like`roboduck.update_config(model_name='gpt-4')`. Passing in a value of None(e.g. `roboduck.update_config(model_name=None)`) will delete that field fromyour config file.1812023-05-23 22:09:407.41 kbdebug.pyA conversational debugger and drop-in replacement for pdb. Python's defaultinteractive debugging session is already a crude conversation with yourprogram or interpreter, in a sense - this just lets your program communicate toyou more effectively.Quickstart----------Here's a broken version of bubble sort that places a `duck()` call on thesecond to last line where you might normally call `breakpoint()`.```from roboduck import duckdef bubble_sort(nums):for i in range(len(nums)):for j in range(len(nums) - 1):if nums[j] > nums[j + 1]:nums[j + 1] = nums[j]nums[j] = nums[j + 1]duck()   # <--------------------------- instead of breakpoint()return numsnums = [3, 1, 9, 2, 1]bubble_sort(nums)```5712023-05-31 00:16:1322.98 kbdecorators.pyMiscellaneous decorators used throughout the library.3052023-05-29 15:21:2310.86 kberrors.pyErrors that explain themselves! Or more precisely, errors that are explainedto you by a gpt-esque model. Simply importing this module will change python'sdefault behavior when it encounters an error.Quickstart----------Importing the errors module automatically enables optional error explanations.`disable()` reverts to python's regular behavior on errors. `enable()` can beused to re-enable error explanations or to change settings. For example,setting auto=True automatically explains all errors rather than asking the userif they want an explanation (y/n) when an error occurs.```from roboduck import errorsdata = {'x': 0}y = data.xerrors.disable()y = data.xerrors.enable(auto=True)y = data.x```2792023-05-29 16:15:0211.44 kbipy_utils.pyFunctions related to loading, saving, or otherwise working with ipythonsessions or jupyter notebooks.1862023-05-24 21:37:485.70 kblogging.pyLogger that attempts to diagnose and propose a solution for any errors itis asked to log. Unlike our debugger and errors modules, explanations arenot streamed because the intended use case is not focused on live development.Quickstart----------```from roboduck import logginglogger = logging.getLogger(path='/tmp/log.txt')data = {'x': 0}try:x = data.xexcept Exception as e:logger.error(e)```1582023-05-29 16:15:026.33 kbmagic.pyGPT-powered rough equivalent of the `%debug` Jupyter magic. After an erroroccurs, just run %duck in the next cell to get an explanation. This is verysimilar to using the errors module, but is less intrusive - you only call itwhen you want an explanation, rather than having to type y/n after each error.We also provide `paste` mode, which attempts to paste a solution into a newcode cell below, and `interactive` mode, which throws you into a conversationaldebugging session (technically closer to the original `%debug` magicfunctionality.Quickstart----------```# cell 1from roboduck import magicnums = [1, 2, 3]nums.add(4)``````# cell 2%duck```1272023-05-30 22:28:435.18 kbutils.pyUtility functions used by other roboduck modules.4202023-05-27 21:32:2915.14 kbEnd of auto-generated file data. Do not add anything below this.