Metadata-Version: 2.1
Name: ai-powered
Version: 0.2.4
Summary: The easiest way to develop AI-Powered applications
Home-page: https://github.com/luochen1990/ai_powered
Author: Luo Chen
Author-email: luochen1990@gmail.com
Requires-Python: >=3.10,<4
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: msgspec (>=0.18.6,<0.19.0)
Requires-Dist: openai (>=1.35.14,<2.0.0)
Project-URL: Repository, https://github.com/luochen1990/ai_powered
Description-Content-Type: text/markdown

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 (primarily referring to Large Language Models) 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 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.

Usage
---

Installation is done by `pip install ai_powered` or `poetry add ai_powered`.

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 in fact, this model can be replicated in any other language that supports runtime type annotations.
- At present, OpenAI's function calling capability cannot recognize references in the schema, so problems may arise when types become complex enough to generate references. This can be alleviated with deref, but when encountering recursive types, ref has to be kept, so this issue may ultimately require LLM providers to add such data in their training datasets to truly resolve the problem.
- 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).

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

1. The project will always be open source, but I haven't decided which open-source license to use yet. If you don't mind this, you can directly PR; otherwise, we might need to discuss the license issue first.
2. 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.
3. Test coverage will be continuously monitored. It is recommended to always provide tests for your code, and even prepare the tests before coding.
4. 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).

