chore: add en README

README.md

@@ -3,3 +3,103 @@ 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
+Translated Text:
+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 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).