AI Powered
==========

[![codecov](https://codecov.io/github/luochen1990/ai_powered/graph/badge.svg?token=OBG1BWIKC2)](https://codecov.io/github/luochen1990/ai_powered)

Motivation
---

Currently, AI has reached a stage of considerable practicality, yet many traditional software applications have not yet benefited from it. This project aims to provide convenient tools for integrating AI capabilities (primarily referring to Large Language Models) into various software.

With these tools, you don't need to redesign the entire software to leverage AI capabilities, nor do you need to add any user-visible functional modules. As long as you find that a function in your project could potentially be better answered by AI, you can replace its implementation with AI.

Even so, you don't need to learn anything about the OpenAI SDK to achieve these tasks, all within just a few minutes!

Features
--------

1. The `@ai_powered` decorator auto provide implementation for your python function with signature and docstring (call LLM underground)
2. The `@make_tool` decorator turn your python function (with type annotations) into tools available by OpenAI API
3. The `ChatBot` class can be inherited to create your own chatbot with tools empowered
4. Full async support and sync compatible, use either style you want
5. Strict type annotation (validated by pylance the strict mode)
6. With unit test, and test coverage ratio is monitored

Usage
---

Installation is done by `pip install ai_powered` or `poetry add ai_powered`. ([pypi](https://pypi.org/project/ai-powered/))

And provide your API keys via environment variables ([more details](/doc/en/Configuration.md)):

```shell
export OPENAI_API_KEY=---YOUR-REAL-API-KEY---
```

It provides the following tools:

### `@ai_powered` Decorator

This decorator imbues your function signature with an AI implementation, which reads the docstring and invokes LLM to obtain the function's return value

```python
from ai_powered import ai_powered

@ai_powered
def get_python_expression(expr: str) -> str:
    """ Convert the user-input mathematical expression into a valid Python expression """
    ...
```

You can also use more complex data structures in parameters and return values, but make sure they have complete type annotations

```python
@dataclass
class UserInfo:
    name: str
    country: Optional[str]
    age: Optional[int]

@ai_powered
def extract_user_info(raw_text: str) -> UserInfo:
    ''' Extract user information from this self-introduction '''
    ...
```

More examples can be found [here](/test/examples/ai_powered_decorator/)

### `@make_tool` Decorator

This decorator converts ordinary Python functions into tools that can be used by the [function calling](https://platform.openai.com/docs/guides/function-calling) feature of LLM.

```python
from ai_powered import make_tool
import openai

@make_tool
def calculator(python_expression: str) -> str:
    ''' Evaluate a Python expression (only support built-in functions), which can be used to solve mathematical problems. '''
    return safe_eval(python_expression)

client = openai.OpenAI()
response = client.chat.completions.create(
    model = "gpt-4o-mini",
    messages = self.conversation,
    tools = [ calculator.schema() ],
    tool_choice = calculator.choice()
)
```

### `ChatBot` 类

This class implements an AI chatbot. You can inherit from it to create your own ChatBot subclass, specifying the system prompts and tools to use. It will help you handle the complex process of tool invocation.

```python
class MyChatBot (ChatBot):
    system_prompt = '''
    Please answer the user's questions. If any calculations are required, use the calculator available in the tool. It supports complex Python expressions. When using it, make sure to convert the user's mathematical expression to a valid Python expression. Do not use any undefined functions; if the user's expression includes function calls, convert them to Python's built-in functions or syntax.
    '''
    tools = (calculator,)

if __name__ == "__main__":
    bot = MyChatBot()
    print(bot.chat('hello, please tell me the result of 2^10 + 3^4'))
    print(bot.chat('and what is above result divided by 2?'))
    print(f"{bot.conversation =}")
```

More examples can be found [here](/test/examples/chat_bot/)


Current Limitations and Future Plans
----------------------------

- Currently, only a Python implementation is provided, but it is possible to be replicated in any other language that supports runtime type annotations.
- The data generated by the current LLM does not strictly adhere to the provided JSON Schema 100% of the time. The error rate may decrease as LLM providers continue to train, but in the end, we may need to introduce a retry mechanism to get it to approach 100% correctness (a retry mechanism is currently being planned). (Things changed [now](https://openai.com/index/introducing-structured-outputs-in-the-api/), but there is still models which does not support this)
- At present, recursive structures is not supported, since some LLM function calling capability cannot recognize references in the schema, so we deref all the references in the schema, but deref doesn't work with recursive types, so this issue may ultimately require LLM providers to add such data in their training datasets to truly resolve the problem.

Regarding Code Contribution
--------------------------

1. Currently, all code is under Pyright strict mode type checking, and any type errors will be blocked by GitHub Actions. We do not recommend using `Any` or `#type: ignore` unless absolutely necessary.
2. Test coverage will be continuously monitored. It is recommended to always provide tests for your code, and even prepare the tests before coding. tips: you can mark tests for WIP features use `@pytest.mark.xfail`.
3. Regarding the development environment, it is recommended to install `nix` and `direnv` so that you automatically get a usable development environment. Of course, `poetry shell` is also a good choice (if you are already using poetry).

Acknowledgments
--------------

- [instructor](https://jxnl.github.io/instructor/): It has made significant contributions to advancing LLM in supporting structured output.
- [msgspec](https://github.com/jcrist/msgspec): Rapid serialization/deserialization of data and providing JSON schema, which is one of the most crucial libraries relied upon by this project.
