# ai_shell
OpenAI-centric shell for giving safe, chat-optimized, filesystem access to an Assistant as a "tool".
Even if you trust the bot to run bash directly on your machine or docker container, standard tools will run up your
bill with excess tokens in the reply, or a command generates too few tokens and the bot doesn't know what is
going on.
This is an alternative to `code_interpreter`, tools running code in docker container locally, or tools running arbitrary
shell code locally.
## Installation
`pip install ai_shell`
## Usage
See these full examples. As long as the OPENAI_API_KEY environment variable is set, you can run these examples.
- [Pylint bot](https://github.com/matthewdeanmartin/ai_shell/blob/main/ai_shell/demo_bots/pylint_bot.py) will
attempt to
fix python
code lint issues.
- [Test writer bot](https://github.com/matthewdeanmartin/ai_shell/blob/main/ai_shell/demo_bots/test_writer_bot.py) will attempt to
write unit tests for python code.
- [Tool tester bot](https://github.com/matthewdeanmartin/ai_shell/blob/main/ai_shell/demo_bots/tool_tester_bot.py) tries out tools
to see if they basically work.
To execute demo bots, run these commands and follow initialization instructions if needed. They all expect to
manipulate python code in an /src/ folder.
```shell
python -m ai_shell.demo_bots.docs_writer_bot
python -m ai_shell.demo_bots.pylint_bot
python -m ai_shell.demo_bots.test_writer_bot
python -m ai_shell.demo_bots.tool_tester_bot
python -m ai_shell.demo_bots.todo_bot
```
This is the python interface to the tools, how you're expected to wire up the tool to your bot.
```python
import ai_shell
cat = ai_shell.CatTool(".")
print(cat.cat(["file.py"]))
print(cat.cat_markdown(["file.py"]))
ls = ai_shell.LsTool(".")
print(ls.ls("docs"))
print(ls.ls_markdown("docs"))
```
This is the smallest example to illustrate basic capabilities, also
see [here](https://github.com/matthewdeanmartin/ai_shell/blob/main/example_tiny_bot.py).
```python
import asyncio
import ai_shell
async def main():
def static_keep_going(toolkit: ai_shell.ToolKit):
usage = toolkit.get_tool_usage_for("ls")
if usage["count"] > 0:
return (
"Great job! You've used ls. Summarize in paragraph form and we're done."
)
return (
"You haven't used the ls tool yet. Do you have access to the ls tool? If"
" there is a problem report it to the report_text tool to end the session."
)
# Creates temporary bots
bot = ai_shell.TaskBot(
ai_shell.Config(),
name="Folder inspection bot.",
bot_instructions="Run the ls tool and tell me what you see.",
model="gpt-3.5-turbo-1106",
dialog_logger_md=ai_shell.DialogLoggerWithMarkdown("./tmp"),
)
await bot.initialize()
the_ask = f"""You are in the './' folder. You do not need to guess the pwd, it is './'.
Run ls and tell me what you see in paragraph format."""
await bot.basic_tool_loop(
the_ask=the_ask,
root_folder="./src",
tool_names=[
"ls",
"report_text",
],
keep_going_prompt=static_keep_going,
)
if __name__ == "__main__":
asyncio.run(main())
```
This is the cli interface, which is intended for testing, not for bot usage.
```shell
ais cat_markdown --file-paths pyproject.toml
```
## Features in Brief
- Many cli-like tools interfaces, such as ls, cat, grep, head, tail, and git.
- OpenAI glue for all cli tools.
- UX with a bot in mind.
- Security with mischievous but not especially malicious bot in mind.
- Bot (Assistant) boilerplate help
- Support for bots doing one shot tool use and goal function driven tool use.
- Bot have extensibility points.
- TODO: plugin system for tools.
## Analogues supported today
**Directories**: ls, find
**Files**: cat, grep, head, tail
**Editing**: sed, ed, edlin, patch, replace, insert, rewrite, write new
**Data**: cut
**Other**: pycat, token counter, git
**Tasking**: todo
n.b. Every file is read and written as utf-8 strings.
## Prior Art
ai_shell draws inspiration from various command-line interface (CLI) tools and shell environments, integrating
features from traditional shells with OpenAI's language models. It is designed to provide an easy and secure interface
for AI-assisted file system interactions, keeping in mind both usability and safety.
## Documentation
- [Features](https://github.com/matthewdeanmartin/ai_shell/blob/main/docs/Features.md)
- [Design](https://github.com/matthewdeanmartin/ai_shell/blob/main/docs/Design.md)
- [Use Cases](https://github.com/matthewdeanmartin/ai_shell/blob/main/docs/Usecases.md)
- [TODO](https://github.com/matthewdeanmartin/ai_shell/blob/main/docs/TODO.md)
- [API docs, pdoc3 style](https://matthewdeanmartin.github.io/ai_shell/)
Raw data
{
"_id": null,
"home_page": "https://github.com/matthewdeanmartin/ai_shell",
"name": "ai-shell",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<3.12",
"maintainer_email": "",
"keywords": "openai,chatgpt",
"author": "Matthew Martin",
"author_email": "matthewdeanmartin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b1/9c/58820bfb7b55024564871571e4082dea3c25859724993310d151532fda02/ai_shell-1.0.4.tar.gz",
"platform": null,
"description": "# ai_shell\n\nOpenAI-centric shell for giving safe, chat-optimized, filesystem access to an Assistant as a \"tool\".\n\nEven if you trust the bot to run bash directly on your machine or docker container, standard tools will run up your\nbill with excess tokens in the reply, or a command generates too few tokens and the bot doesn't know what is\ngoing on.\n\nThis is an alternative to `code_interpreter`, tools running code in docker container locally, or tools running arbitrary\nshell code locally.\n\n## Installation\n\n`pip install ai_shell`\n\n## Usage\n\nSee these full examples. As long as the OPENAI_API_KEY environment variable is set, you can run these examples.\n\n- [Pylint bot](https://github.com/matthewdeanmartin/ai_shell/blob/main/ai_shell/demo_bots/pylint_bot.py) will\n attempt to\n fix python\n code lint issues.\n- [Test writer bot](https://github.com/matthewdeanmartin/ai_shell/blob/main/ai_shell/demo_bots/test_writer_bot.py) will attempt to\n write unit tests for python code.\n- [Tool tester bot](https://github.com/matthewdeanmartin/ai_shell/blob/main/ai_shell/demo_bots/tool_tester_bot.py) tries out tools\n to see if they basically work.\n\nTo execute demo bots, run these commands and follow initialization instructions if needed. They all expect to\nmanipulate python code in an /src/ folder.\n\n```shell\npython -m ai_shell.demo_bots.docs_writer_bot\npython -m ai_shell.demo_bots.pylint_bot\npython -m ai_shell.demo_bots.test_writer_bot\npython -m ai_shell.demo_bots.tool_tester_bot\npython -m ai_shell.demo_bots.todo_bot\n```\n\nThis is the python interface to the tools, how you're expected to wire up the tool to your bot.\n\n```python\nimport ai_shell\n\ncat = ai_shell.CatTool(\".\")\nprint(cat.cat([\"file.py\"]))\nprint(cat.cat_markdown([\"file.py\"]))\n\nls = ai_shell.LsTool(\".\")\nprint(ls.ls(\"docs\"))\nprint(ls.ls_markdown(\"docs\"))\n```\n\nThis is the smallest example to illustrate basic capabilities, also\nsee [here](https://github.com/matthewdeanmartin/ai_shell/blob/main/example_tiny_bot.py).\n\n```python\nimport asyncio\nimport ai_shell\n\n\nasync def main():\n def static_keep_going(toolkit: ai_shell.ToolKit):\n usage = toolkit.get_tool_usage_for(\"ls\")\n if usage[\"count\"] > 0:\n return (\n \"Great job! You've used ls. Summarize in paragraph form and we're done.\"\n )\n return (\n \"You haven't used the ls tool yet. Do you have access to the ls tool? If\"\n \" there is a problem report it to the report_text tool to end the session.\"\n )\n\n # Creates temporary bots\n bot = ai_shell.TaskBot(\n ai_shell.Config(),\n name=\"Folder inspection bot.\",\n bot_instructions=\"Run the ls tool and tell me what you see.\",\n model=\"gpt-3.5-turbo-1106\",\n dialog_logger_md=ai_shell.DialogLoggerWithMarkdown(\"./tmp\"),\n )\n await bot.initialize()\n the_ask = f\"\"\"You are in the './' folder. You do not need to guess the pwd, it is './'. \n Run ls and tell me what you see in paragraph format.\"\"\"\n await bot.basic_tool_loop(\n the_ask=the_ask,\n root_folder=\"./src\",\n tool_names=[\n \"ls\",\n \"report_text\",\n ],\n keep_going_prompt=static_keep_going,\n )\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\nThis is the cli interface, which is intended for testing, not for bot usage.\n\n```shell\nais cat_markdown --file-paths pyproject.toml\n```\n\n## Features in Brief\n\n- Many cli-like tools interfaces, such as ls, cat, grep, head, tail, and git.\n- OpenAI glue for all cli tools.\n- UX with a bot in mind.\n- Security with mischievous but not especially malicious bot in mind.\n- Bot (Assistant) boilerplate help\n- Support for bots doing one shot tool use and goal function driven tool use.\n- Bot have extensibility points.\n- TODO: plugin system for tools.\n\n## Analogues supported today\n\n**Directories**: ls, find\n\n**Files**: cat, grep, head, tail\n\n**Editing**: sed, ed, edlin, patch, replace, insert, rewrite, write new\n\n**Data**: cut\n\n**Other**: pycat, token counter, git\n\n**Tasking**: todo\n\nn.b. Every file is read and written as utf-8 strings.\n\n## Prior Art\n\nai_shell draws inspiration from various command-line interface (CLI) tools and shell environments, integrating\nfeatures from traditional shells with OpenAI's language models. It is designed to provide an easy and secure interface\nfor AI-assisted file system interactions, keeping in mind both usability and safety.\n\n## Documentation\n\n- [Features](https://github.com/matthewdeanmartin/ai_shell/blob/main/docs/Features.md)\n- [Design](https://github.com/matthewdeanmartin/ai_shell/blob/main/docs/Design.md)\n- [Use Cases](https://github.com/matthewdeanmartin/ai_shell/blob/main/docs/Usecases.md)\n- [TODO](https://github.com/matthewdeanmartin/ai_shell/blob/main/docs/TODO.md)\n- [API docs, pdoc3 style](https://matthewdeanmartin.github.io/ai_shell/)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Filesystem Shell interface that an OpenAI Assitant can use as a tool.",
"version": "1.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/matthewdeanmartin/ai_shell/issues",
"Change Log": "https://github.com/matthewdeanmartin/ai_shell/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/matthewdeanmartin/ai_shell",
"Homepage": "https://github.com/matthewdeanmartin/ai_shell",
"Repository": "https://github.com/matthewdeanmartin/ai_shell"
},
"split_keywords": [
"openai",
"chatgpt"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8cc781b65812ebde3905777e5c7a9f48fb083ba973193ff83e0e09bbe99717aa",
"md5": "dcdfcfda8800a8b6b39d28f61b718240",
"sha256": "8be124a49e4a254c5c102810c935e82747668b2214cc68a80c7b7ad9cd162fc7"
},
"downloads": -1,
"filename": "ai_shell-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dcdfcfda8800a8b6b39d28f61b718240",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<3.12",
"size": 133418,
"upload_time": "2024-01-21T01:01:38",
"upload_time_iso_8601": "2024-01-21T01:01:38.201034Z",
"url": "https://files.pythonhosted.org/packages/8c/c7/81b65812ebde3905777e5c7a9f48fb083ba973193ff83e0e09bbe99717aa/ai_shell-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b19c58820bfb7b55024564871571e4082dea3c25859724993310d151532fda02",
"md5": "e093d8726e7986bff3a18adc37a17d7a",
"sha256": "8abe593a0b3d1b3224e4859188a6007d3b4ce9eab31ea5a0442cef687bc3e22a"
},
"downloads": -1,
"filename": "ai_shell-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "e093d8726e7986bff3a18adc37a17d7a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<3.12",
"size": 98921,
"upload_time": "2024-01-21T01:01:39",
"upload_time_iso_8601": "2024-01-21T01:01:39.482599Z",
"url": "https://files.pythonhosted.org/packages/b1/9c/58820bfb7b55024564871571e4082dea3c25859724993310d151532fda02/ai_shell-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-21 01:01:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matthewdeanmartin",
"github_project": "ai_shell",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "ai-shell"
}
JSON
