Metadata-Version: 2.1
Name: instrukt
Version: 0.6.2
Summary: A versatile AI environment to build and control AI agents using a terminal-based interface.
Home-page: https://github.com/blob42/instrukt
License: AGPL3
Author: Chakib Benziane
Author-email: instrukt@blob42.xyz
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Utilities
Provides-Extra: all
Provides-Extra: coding
Provides-Extra: local
Provides-Extra: openai
Provides-Extra: tools
Requires-Dist: chardet (>=5.2.0,<6.0.0)
Requires-Dist: chromadb (>=0.4.0,<0.5.0)
Requires-Dist: esprima (>=4.0.1,<5.0.0) ; extra == "coding" or extra == "all"
Requires-Dist: instructorembedding (>=1.0.1,<2.0.0) ; extra == "local" or extra == "all"
Requires-Dist: ipython (>=8.13.2,<9.0.0)
Requires-Dist: langchain (==0.0.266)
Requires-Dist: nest-asyncio (>=1.5.6,<2.0.0)
Requires-Dist: openai (>=0.27.8,<0.28.0) ; extra == "openai" or extra == "all"
Requires-Dist: pdfminer-six (>=20221105,<20221106)
Requires-Dist: pydantic (>=1.10.7,<2.0.0)
Requires-Dist: pydantic-yaml (>=0.11.2,<0.12.0)
Requires-Dist: pyperclip (>=1.8.2,<2.0.0)
Requires-Dist: python-magic (>=0.4.27,<0.5.0)
Requires-Dist: pyxdg (>=0.28,<0.29)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: rich (>=13.4.1,<14.0.0)
Requires-Dist: sentence-transformers (>=2.2.2,<3.0.0) ; extra == "local" or extra == "all"
Requires-Dist: textual (>=0.35.1,<0.36.0)
Requires-Dist: tiktoken (>=0.4.0,<0.5.0)
Requires-Dist: tomli (>=2.0.1,<3.0.0)
Requires-Dist: typing-extensions (>=4.7.1,<5.0.0)
Requires-Dist: unstructured[local-inference] (>=0.6.11,<0.7.0)
Requires-Dist: wikipedia (>=1.4.0,<2.0.0) ; extra == "tools" or extra == "all"
Project-URL: Documentation, https://github.com/blob42/instrukt/docs
Project-URL: Repository, https://github.com/blob42/instrukt
Description-Content-Type: text/markdown

# >_⚡  Instrukt

 **Terminal AI Commander at your fingertips**

[coding assistant example](https://github.com/blob42/Instrukt/assets/210457/244fb490-4774-4877-abf6-f64e94f24922)

Checkout more [demos](demos.md) for more examples.

**NOTE**: This is a work in progress, expect bugs and api changes.

## Introduction

Instrukt is a terminal-based environment for AI productivity and development. It offers a platform where users can:

- :robot: Create and instruct modular AI agents
- :card_file_box: Generate document indexes for question-answering
- :toolbox: Create and attach tools to any agent

Agents are simple **drop-in Python packages** that can be extended, shared with others, attached to tools and augmented with document indexes. Instruct them in natural language and, for safety, run them inside secure containers (currently implemented with Docker) to perform tasks in their dedicated, sandboxed space :shield:.

Instrukt uses langchain [LangChain](https://github.com/hwchase17/langchain) and allows you to quickly customize agents and tools to your needs.

Built with: [Langchain](https://github.com/hwchase17/langchain), [Textual](https://github.com/Textualize/textual), [Chroma](https://github.com/chroma-core/chroma)

**Consulting Services**: Need help with Langchain or AI development/deployment ? You can reach out to me at [contact@blob42.xyz](mailto://contact@blob42.xyz)

## TOC

- [Usage](#usage)
- [Features](#features)
- [Supported Platforms](#supported-platforms)
- [LLM Models](#llm-models)
- [Document Indexes and Question-Answering](#document-indexes-and-question-answering)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [Patreon](#patreon)
- [Social](#social)
- [Vision](#vision)
- [License](#license)

## Usage

### Quickstart

- `pip install instrukt[all]`
- export `OPENAI_API_KEY` with your OpenAI API key.
- run `instrukt`
- If the color scheme is broken, export `TERM=xterm-256color`

You can run instrukt on headless server such as a docker container with CUDA support.


#### From source:

- Make sure the latest version of `poetry` is installed.
- Set your virtualenv
- Clone the repository
- Run `poetry install -E tools --with dev` 
- This will install Instrukt including extra tools for agents. 

[See the installation guide for more details](docs/install.md)

### Requirements:

- Export `OPENAI_API_KEY` environment variable with your OpenAI API key.
- Use a modern terminal that supports 24-bit color and mouse input.

### Running:

- Type `instrukt`.
- On the first run, it will create a config file in
  `~/.config/instrukt/instrukt.yml`

#### From source

- If you did not install the dependencies using poetry make sure to install textual dev dependencies with: `pip install textual[dev]`

- From the project's root run: `textual run instrukt.app:InstruktApp`

### Default Agents:

**Chat Q&A**: A simple conversational agent. Attach document indexes and tools to create a question-answering agent. It also serves as an example for making custom agents.

**Demo**: The same agent used in the demo video.

## Features 

#### :computer: Keyboard and Mouse Terminal Interface:

- A terminal-based interface for power keyboard users to instruct AI agents without ever leaving the keyboard.
- Mouse support and [Rich](https://github.com/Textualize/rich) colorful agent outputs such as markdown and source
  code thanks to the [Textual](https://github.com/Textualize/textual) TUI library.
- Run Instrukt in bare metal and access it remotely via SSH and/or terminal
  multiplexer.

#### :robot: Custom AI Agents:
- Design your [own agents](docs/quickstart.md#custom-agents) and custom tools. 
- Agents are simple python packages can be shared and loaded by other users.

#### :wrench: Tools:
- Use the pre-defined toolset or design your own tools.
- Attach or detach tools to agents on-the-go, tailoring your AI workflows to your needs.

#### :books: Chat with your code and documents:
- Index your data and let agents retrieve it for question-answering. 
- Create and organize your indexes with an easy UI.
- Index creation will **auto detect programming languages** and optimize the splitting/chunking
  strategy accordingly.

#### :zap: Prompt Console :
- Integrated REPL-Prompt for quick interaction with agents, and a fast feedback loop for development and testing.
- Add your own custom commands to automate repetitive tasks.
- Builtin prompt/chat history to quickly edit/correct messages.
- Use an external editor for editing messages (e.g. vim). `ctrl+e`

#### :bird: LangChain:

- Leverage the LangChain ecosystem to automate anything.
- Extensible API for integrating with other frameworks.

#### :microscope: Developer Console:
Debug and introspect agents using an in-built IPython console. `ctrl+d`
<p>
<img src="assets/images/ipython-debug-shell.jpg" width=400 alt="ipython debug shell" />
</p>


#### :shield: Secure Containers:

- Run agents inside secure docker containers for safety and privacy.
- Use [gVisor](https://gvisor.dev/) runtime for a full isolation of the agent.

**note**: The docker agent is only available to [Patreon](#patreon) supporters as an early preview.


## Document Indexes and Question-Answering

- Indexes can be  created using OpenAI or locally hosted embedding models.
- They are stored locally using the [Chroma](https://github.com/chroma-core/chroma) embedding database.
- You create and manage indexes using the **Index Management** UI (press `i`)
- Indexing a directory will auto detect programming languages and use an appropriate
  splitting strategy optimized for the target language.
- Indexes can be attached to any agent as a **retrieval** tool using the `index` menu
  in the top of the agent's window.
- Once an index is attached you can do question-answering and the agent will
  lookup your indexed documents whenever they are mentioned or needed.

## Supported platforms:

- Linux/Mac.
- Windows tested under WSL2.

### LLM Models

- Currently only **OpenAI** supported.
- Using private local models is the **next priority**.

## Roadmap

- [ ] Private local models
    - [ ] Use text-generation-webui API
    - [ ] Emulate [PrivateGPT](https://github.com/imartinez/privateGPT)
    - [ ] Use a self hosted [go-skynet/LocalAI](https://github.com/go-skynet/LocalAI)
    - [x] Local embeddings
        - [x] HF SetenceTransformers or other embeddings models.
        - [x] [Instructor Embeddings](https://instructor-embedding.github.io/)
- Indexing and embeddings
    - [x] Index directories and auto detect content. ( see `AutoDirLoader`)
    - [x] Detect programming languages and use the appropriate splitter.
    - [ ] Load a git repository from URL
    - [ ] Load any webpage / website.

- [ ] Documentation
    - [ ] Creating agents
    - [ ] Creating tools
    - [ ] Indexing and chat with documents and source code.
    - [ ] Example use cases  
    - [ ] Tutorials for users non familiar with AI/LLM terms.

## Contributing

Any contribution, feedback and PR is welcome !

You can help with:

- Testing and creating Issues for bugs or features that would be useful.
- If you have technical skills, you are welcome to create a PR.
- If you don't have technical skills you can help with documentation, adding examples
  and tutorials or create new user stories.

## Patreon

By becoming a patron, you will help me continue committing time to the development of Instrukt and bring to life all the planned features. Check out the [Patreon page](https://www.patreon.com/Instrukt) for more details on the rewards for early supporters.

## Social

Join the [Discord](https://discord.gg/wxRwRcJ7) server to keep updated on the progress or ask for help.

## Vision

I believe that AI should be accessible to everyone and not a walled garden for big corporations and SaaS services. 

I hope my contributions will help create tools that empower users without compromising their freedoms. The long-term goal for Instrukt is to make it usable with minimal reliance on external services, giving users the choice to opt for local models and self-hosted services.

# License

Copyright (c) 2023 Chakib Ben Ziane. All Rights Reserved.

Instrukt is licensed with a AGPL license, in short this means that it can be used by anyone for any purpose. However, if you decide to make a publicly available instance your users are entitled to a copy of the source code including all modifications that you have made (which needs to be available trough an interface such as a button on your website), you may also not distribute this project in a form that does not contain the source code (Such as compiling / encrypting the code and distributing this version without also distributing the source code that includes the changes that you made. You are allowed to distribute this in a closed form if you also provide a separate archive with the source code.).

