From 225260be5b87eaf34557fb4b3380bf9de45a1fca Mon Sep 17 00:00:00 2001 From: jameszyao Date: Fri, 26 Apr 2024 20:42:15 +0800 Subject: [PATCH] chore: update examples and readme --- README.md | 131 ++++++++++++------- examples/assistant/chat_with_assistant.ipynb | 6 +- examples/crud/assistant_crud.ipynb | 64 +++++---- examples/crud/retrieval_crud.ipynb | 38 +++--- taskingai/retrieval/record.py | 4 +- 5 files changed, 138 insertions(+), 105 deletions(-) diff --git a/README.md b/README.md index 2827aa5..eefb891 100644 --- a/README.md +++ b/README.md @@ -1,129 +1,172 @@ # TaskingAI-client -The TaskingAI Python client for creating and managing AI-driven applications. +The official TaskingAI Python client. For more information, see the docs at [TaskingAI Documentation](https://docs.tasking.ai/) +## Prerequisites + +The TaskingAI client is compatible with Python 3.8 and above. + ## Installation -Install the latest released version using pip: +Use `pip` to install the TaskingAI Python client. + +```shell +# Install the latest version +pip install taskingai + +# Install a specific version +pip install taskingai==0.2.2 +``` + +## Usage + +### Initialization + +Before you can use the TaskingAI SDK, you must have your TaskingAI project set up and running. For community version, visit [TaskingAI Community](https://www.github.com/taskingai/taskingai) to get started. For cloud version, visit [TaskingAI Cloud](https://www.tasking.ai) to sign up first. + +You need to initialize the TaskingAI Python client with an API key you obtain from the TaskingAI console. You can set the API key as an environment variable or pass it directly to the `init` function. + +#### Using environment variables (Recommended) + +Set it as an environment variable on your local system, and the SDK will automatically load the key without passing the `api_key` parameter in the `init` function. ```shell -pip3 install taskingai +export TASKINGAI_API_KEY=$YOUR_API_KEY +``` + +When you run your Python script, the SDK will automatically pick up the API key from the environment variable. + +```python +import taskingai +# taskingai.init() +# No need to initialize the SDK with the API key +``` + +#### Passing the API key directly + +You can also specify an API key to the SDK by passing it as a parameter to the init function: + +```python +import taskingai +taskingai.init(api_key="YOUR_API_KEY") ``` -## Quickstart +If you use community version, you can set the base URL to the TaskingAI server by passing it to the `init` function: -Here's how you can quickly start building and managing AI-driven applications using the TaskingAI client. +```python +import taskingai +taskingai.init(api_key="YOUR_API_KEY", host="http://localhost:8080") +``` ### Assistants -Explore the ease of creating and customizing your own AI assistants with TaskingAI to enhance user interactions. +The Assistant system in TaskingAI represents a sophisticated framework designed to create and manage AI agents with customizable functionalities. + +Here is an example of how to create, update, and delete an assistant: ```python import taskingai -from taskingai.assistant import * -from taskingai.assistant.memory import AssistantNaiveMemory # Initialize your API key if you haven't already set it in the environment taskingai.init(api_key="YOUR_API_KEY") # Create an assistant -assistant = create_assistant( +asst = taskingai.assistant.create_assistant( model_id="YOUR_MODEL_ID", - memory=AssistantNaiveMemory(), + memory={"type": "naive"}, system_prompt_template=["You are a professional assistant."], ) -print(f"Assistant created: {assistant.id}") +print(f"Assistant created: {asst.assistant_id}") # Get details about the assistant -assistant_details = get_assistant(assistant_id=assistant.id) +assistant_details = taskingai.assistant.get_assistant(assistant_id=asst.assistant_id) print(f"Assistant details: {assistant_details}") # Update the assistant's description -update_assistant( - assistant_id=assistant.id, - description="An updated description for my assistant." +taskingai.assistant.update_assistant( + assistant_id=asst.assistant_id, + description="Updated description" ) print(f"Assistant updated.") # Delete the assistant when done -delete_assistant(assistant_id=assistant.id) +taskingai.assistant.delete_assistant(assistant_id=asst.assistant_id) print("Assistant deleted successfully.") ``` ### Retrieval -Leverage TaskingAI's retrieval capabilities to store, manage, and extract information, making your applications smarter and more responsive. +TaskingAI offers comprehensive tools for the retrieval system, ranging from straightforward to intricate setups. Here is an example of how to create, add, retrieve, and delete a record in a collection: ```python import taskingai -from taskingai.retrieval import * # Create a collection for storing and retrieving data -collection = create_collection( - embedding_model_id="YOUR_MODEL_ID", +coll = taskingai.retrieval.create_collection( + embedding_model_id="YOUR_EMBEDDING_MODEL_ID", capacity=1000 ) -print(f"Collection created: {collection.id}") +print(f"Collection created: {coll.collection_id}") # Add a record to the collection -record = create_record( - collection_id=collection.id, - content="Example text for machine learning.", - text_splitter=TokenTextSplitter(chunk_size=200, chunk_overlap=20), +record = taskingai.retrieval.create_record( + collection_id=coll.collection_id, + type="text", + content="Machine learning is ...", + text_splitter={"type": "token", "chunk_size": 200, "chunk_overlap": 20} ) -print(f"Record added to collection: {record.id}") +print(f"Record added to collection: {record.record_id}") # Retrieve the record from the collection -retrieved_record = get_record( - collection_id=collection.id, - record_id=record.id +retrieved_record = taskingai.retrieval.get_record( + collection_id=coll.collection_id, + record_id=record.record_id ) -print(f"Record retrieved: {retrieved_record.text}") +print(f"Record retrieved: {retrieved_record.content}") # Delete the record -delete_record( - collection_id=collection.id, - record_id=record.id +taskingai.retrieval.delete_record( + collection_id=coll.collection_id, + record_id=record.record_id ) print("Record deleted.") # Delete the collection -delete_collection(collection_id=collection.id) +taskingai.retrieval.delete_collection(collection_id=coll.collection_id) print("Collection deleted.") ``` ### Tools -Utilize TaskingAI's tools to create actions that enable your assistant to interact with external APIs and services, enriching the user experience. +The Tools module in TaskingAI is an essential suite designed to augment the capabilities of TaskingAI agents. Here is an example of how to create, run, and delete a tool action: ```python import taskingai -from taskingai.tool import * # Define a schema for the tool action -NUMBERS_API_SCHEMA = { +OPENAPI_SCHEMA = { # Schema definition goes here } # Create a tool action based on the defined schema -actions = bulk_create_actions( - openapi_schema=NUMBERS_API_SCHEMA, - authentication=ActionAuthentication(type=ActionAuthenticationType.NONE) +actions = taskingai.tool.bulk_create_actions( + openapi_schema=OPENAPI_SCHEMA, + authentication={"type": "none"}, ) action = actions[0] -print(f"Action created: {action.id}") +print(f"Action created: {action.action_id}") # Run the action for a test purpose -result = run_action( - action_id=action.id, +result = taskingai.tool.run_action( + action_id=action.action_id, parameters={"number": 42} ) print(f"Action result: {result}") # Delete the action when done -delete_action(action_id=action.id) +taskingai.tool.delete_action(action_id=action.action_id) print("Action deleted.") ``` diff --git a/examples/assistant/chat_with_assistant.ipynb b/examples/assistant/chat_with_assistant.ipynb index 00393f3..8f0f679 100644 --- a/examples/assistant/chat_with_assistant.ipynb +++ b/examples/assistant/chat_with_assistant.ipynb @@ -111,7 +111,7 @@ "from taskingai.assistant.memory import AssistantMessageWindowMemory\n", "\n", "# choose an available chat_completion model from your project\n", - "model_id = \"YOUR_MODEL_ID\"\n", + "model_id = \"YOUR_CHAT_COMPLETION_MODEL_ID\"\n", "\n", "assistant: Assistant = taskingai.assistant.create_assistant(\n", " model_id=model_id,\n", @@ -129,10 +129,6 @@ " ToolRef(\n", " type=ToolType.ACTION,\n", " id=action.action_id,\n", - " ), \n", - " ToolRef(\n", - " type=ToolType.ACTION,\n", - " id=action.action_id,\n", " )\n", " ],\n", " retrievals=[],\n", diff --git a/examples/crud/assistant_crud.ipynb b/examples/crud/assistant_crud.ipynb index 88aa41f..2e154a2 100644 --- a/examples/crud/assistant_crud.ipynb +++ b/examples/crud/assistant_crud.ipynb @@ -25,11 +25,8 @@ "metadata": {}, "outputs": [], "source": [ - "from taskingai.assistant import Assistant, Chat\n", - "from taskingai.assistant.memory import AssistantNaiveMemory\n", - "\n", "# choose an available chat_completion model from your project\n", - "model_id = \"YOUR_MODEL_ID\"" + "model_id = \"YOUR_CHAT_COMPLETION_MODEL_ID\"" ] }, { @@ -47,24 +44,27 @@ "metadata": {}, "outputs": [], "source": [ - "from taskingai.assistant import RetrievalConfig, RetrievalMethod\n", - "\n", "# create an assistant\n", - "def create_assistant() -> Assistant:\n", - " assistant: Assistant = taskingai.assistant.create_assistant(\n", + "def create_assistant():\n", + " assistant = taskingai.assistant.create_assistant(\n", " model_id=model_id,\n", " name=\"Customer Service Assistant\",\n", " description=\"A professional assistant for customer service.\",\n", " system_prompt_template=[\"You are a professional customer service assistant speaking {{language}}.\"],\n", - " memory=AssistantNaiveMemory(),\n", + " memory={\"type\": \"naive\",},\n", " tools=[],\n", " retrievals=[],\n", - " retrieval_configs=RetrievalConfig(top_k=3, max_tokens=4096, method=RetrievalMethod.USER_MESSAGE),\n", + " retrieval_configs={\n", + " \"top_k\": 3, \n", + " \"max_tokens\": 4096,\n", + " \"method\": \"user_message\"\n", + " },\n", " metadata={\"foo\": \"bar\"},\n", " )\n", " return assistant\n", "\n", - "assistant: Assistant = create_assistant()\n", + "assistant = create_assistant()\n", + "assistant_id: str = assistant.assistant_id\n", "print(f\"created assistant: {assistant}\\n\")" ] }, @@ -77,11 +77,7 @@ "outputs": [], "source": [ "# get assistant\n", - "assistant_id: str = assistant.assistant_id\n", - "assistant: Assistant = taskingai.assistant.get_assistant(\n", - " assistant_id=assistant_id\n", - ")\n", - "\n", + "assistant = taskingai.assistant.get_assistant(assistant_id)\n", "print(f\"got assistant: {assistant}\\n\")" ] }, @@ -94,13 +90,16 @@ "outputs": [], "source": [ "# update assistant\n", - "assistant: Assistant = taskingai.assistant.update_assistant(\n", + "assistant = taskingai.assistant.update_assistant(\n", " assistant_id=assistant_id,\n", - " name=\"New Assistant\",\n", - " retrieval_configs=RetrievalConfig(top_k=4, max_tokens=8192, method=RetrievalMethod.USER_MESSAGE),\n", + " name=\"New Assistant Name\",\n", + " retrieval_configs={\n", + " \"top_k\": 5, \n", + " \"max_tokens\": 2048,\n", + " \"method\": \"user_message\"\n", + " },\n", ")\n", - "\n", - "print(f\"updated assistant: {assistant}\\n\")\n" + "print(f\"updated assistant: {assistant}\\n\")" ] }, { @@ -112,7 +111,7 @@ "outputs": [], "source": [ "# delete assistant\n", - "taskingai.assistant.delete_assistant(assistant_id=assistant_id)\n", + "taskingai.assistant.delete_assistant(assistant_id)\n", "print(f\"deleted assistant: {assistant_id}\\n\")" ] }, @@ -149,10 +148,10 @@ "outputs": [], "source": [ "# create a new assistant\n", - "assistant: Assistant = create_assistant()\n", + "assistant = create_assistant()\n", "\n", "# create a chat\n", - "chat: Chat = taskingai.assistant.create_chat(\n", + "chat = taskingai.assistant.create_chat(\n", " assistant_id=assistant.assistant_id,\n", ")\n", "print(f\"created chat: {chat.chat_id} for assistant: {assistant.assistant_id}\\n\")" @@ -168,7 +167,7 @@ "source": [ "# get chat\n", "chat_id: str = chat.chat_id\n", - "chat: Chat = taskingai.assistant.get_chat(\n", + "chat = taskingai.assistant.get_chat(\n", " assistant_id=assistant.assistant_id,\n", " chat_id=chat_id,\n", ")\n", @@ -184,7 +183,7 @@ "outputs": [], "source": [ "# update chat\n", - "chat: Chat = taskingai.assistant.update_chat(\n", + "chat = taskingai.assistant.update_chat(\n", " assistant_id=assistant.assistant_id,\n", " chat_id=chat_id,\n", " name=\"New Chat\",\n", @@ -217,15 +216,12 @@ }, "outputs": [], "source": [ - "# list chats \n", + "# create chats \n", "for _ in range(3):\n", - " taskingai.assistant.create_chat(\n", - " assistant_id=assistant.assistant_id,\n", - " )\n", + " taskingai.assistant.create_chat(assistant.assistant_id)\n", "\n", - "chats = taskingai.assistant.list_chats(\n", - " assistant_id=assistant.assistant_id,\n", - ")\n", + "# list chats\n", + "chats = taskingai.assistant.list_chats(assistant.assistant_id)\n", "print(f\"num chats = {len(chats)}\\n\")" ] }, @@ -238,7 +234,7 @@ "outputs": [], "source": [ "# delete assistant\n", - "taskingai.assistant.delete_assistant(assistant_id=assistant.assistant_id)" + "taskingai.assistant.delete_assistant(assistant.assistant_id)" ] } ], diff --git a/examples/crud/retrieval_crud.ipynb b/examples/crud/retrieval_crud.ipynb index 1f42ed1..5d8fae9 100644 --- a/examples/crud/retrieval_crud.ipynb +++ b/examples/crud/retrieval_crud.ipynb @@ -32,8 +32,6 @@ }, "outputs": [], "source": [ - "from taskingai.retrieval import Collection, Record, Chunk, TokenTextSplitter\n", - "\n", "# choose an available text_embedding model from your project\n", "embedding_model_id = \"YOUR_EMBEDDING_MODEL_ID\"" ] @@ -71,14 +69,14 @@ "outputs": [], "source": [ "# create a collection\n", - "def create_collection() -> Collection:\n", - " collection: Collection = taskingai.retrieval.create_collection(\n", + "def create_collection():\n", + " collection = taskingai.retrieval.create_collection(\n", " embedding_model_id=embedding_model_id,\n", " capacity=1000 # maximum text chunks can be stored \n", " )\n", " return collection\n", "\n", - "collection: Collection = create_collection()\n", + "collection = create_collection()\n", "print(f\"created collection: {collection}\")" ] }, @@ -93,7 +91,7 @@ "source": [ "# get collection\n", "collection_id: str = collection.collection_id\n", - "collection: Collection = taskingai.retrieval.get_collection(\n", + "collection = taskingai.retrieval.get_collection(\n", " collection_id=collection_id\n", ")\n", "\n", @@ -110,7 +108,7 @@ "outputs": [], "source": [ "# update collection\n", - "collection: Collection = taskingai.retrieval.update_collection(\n", + "collection = taskingai.retrieval.update_collection(\n", " collection_id=collection_id,\n", " metadata={\"foo\": \"bar\"}\n", ")\n", @@ -168,7 +166,7 @@ "outputs": [], "source": [ "# create a new collection\n", - "collection: Collection = create_collection()\n", + "collection = create_collection()\n", "print(collection)" ] }, @@ -190,7 +188,7 @@ "outputs": [], "source": [ "# create a new text record\n", - "record: Record = taskingai.retrieval.create_record(\n", + "record = taskingai.retrieval.create_record(\n", " collection_id=collection.collection_id,\n", " type=\"text\",\n", " title=\"Machine learning\",\n", @@ -237,7 +235,7 @@ "outputs": [], "source": [ "# create a new web record\n", - "record: Record = taskingai.retrieval.create_record(\n", + "record = taskingai.retrieval.create_record(\n", " collection_id=collection.collection_id,\n", " type=\"web\",\n", " title=\"Tasking AI\",\n", @@ -284,7 +282,7 @@ "# upload a file first\n", "from taskingai.file import upload_file\n", "\n", - "file = upload_file(file=open(\"YOUR_FILE_PATH\", \"rb\"), purpose=\"record_file\")\n", + "file = upload_file(file=open(\"../../test/files/test.pdf\", \"rb\"), purpose=\"record_file\")\n", "print(f\"uploaded file id: {file.file_id}\")" ] }, @@ -294,7 +292,7 @@ "outputs": [], "source": [ "# create a new file record\n", - "record: Record = taskingai.retrieval.create_record(\n", + "record = taskingai.retrieval.create_record(\n", " collection_id=collection.collection_id,\n", " type=\"file\",\n", " title=\"Machine Learning\",\n", @@ -313,7 +311,7 @@ "execution_count": null, "outputs": [], "source": [ - "new_file = upload_file(file=open(\"NEW_FILE_PATH\", \"rb\"), purpose=\"record_file\")\n", + "new_file = upload_file(file=open(\"../../test/files/test.docx\", \"rb\"), purpose=\"record_file\")\n", "print(f\"new uploaded file id: {new_file.file_id}\")" ], "metadata": { @@ -434,7 +432,7 @@ "outputs": [], "source": [ "# create a new text record\n", - "chunk: Chunk = taskingai.retrieval.create_chunk(\n", + "chunk = taskingai.retrieval.create_chunk(\n", " collection_id=collection.collection_id,\n", " content=\"The dog is a domesticated descendant of the wolf. Also called the domestic dog, it is derived from extinct gray wolves, and the gray wolf is the dog's closest living relative. The dog was the first species to be domesticated by humans.\",\n", ")\n", @@ -525,7 +523,7 @@ " collection_id=collection.collection_id,\n", " type=\"text\",\n", " content=\"Machine learning is a subfield of artificial intelligence (AI) that involves the development of algorithms that allow computers to learn from and make decisions or predictions based on data. The term \\\"machine learning\\\" was coined by Arthur Samuel in 1959. In other words, machine learning enables a system to automatically learn and improve from experience without being explicitly programmed. This is achieved by feeding the system massive amounts of data, which it uses to learn patterns and make inferences. There are three main types of machine learning: 1. Supervised Learning: This is where the model is given labeled training data and the goal of learning is to generalize from the training data to unseen situations in a principled way. 2. Unsupervised Learning: This involves training on a dataset without explicit labels. The goal might be to discover inherent groupings or patterns within the data. 3. Reinforcement Learning: In this type, an agent learns to perform actions based on reward/penalty feedback to achieve a goal. It's commonly used in robotics, gaming, and navigation. Deep learning, a subset of machine learning, uses neural networks with many layers (\\\"deep\\\" structures) and has been responsible for many recent breakthroughs in AI, including speech recognition, image recognition, and natural language processing. It's important to note that machine learning is a rapidly developing field, with new techniques and applications emerging regularly.\",\n", - " text_splitter=TokenTextSplitter(chunk_size=200, chunk_overlap=20)\n", + " text_splitter={\"type\": \"token\", \"chunk_size\": 400, \"chunk_overlap\": 20},\n", ")\n", "\n", "taskingai.retrieval.create_chunk(\n", @@ -553,15 +551,15 @@ { "cell_type": "code", "execution_count": null, - "id": "b97aaa156f586e34", - "metadata": { - "collapsed": false - }, "outputs": [], "source": [ "# delete collection\n", "taskingai.retrieval.delete_collection(collection_id=collection.collection_id)" - ] + ], + "metadata": { + "collapsed": false + }, + "id": "b97aaa156f586e34" } ], "metadata": { diff --git a/taskingai/retrieval/record.py b/taskingai/retrieval/record.py index 8a3433c..094f71e 100644 --- a/taskingai/retrieval/record.py +++ b/taskingai/retrieval/record.py @@ -161,7 +161,7 @@ def create_record( text_splitter = text_splitter if isinstance(text_splitter, TextSplitter) else TextSplitter(**text_splitter) body = RecordCreateRequest( - title=title, + title=title or "", type=type, text_splitter=text_splitter, content=content, @@ -202,7 +202,7 @@ async def a_create_record( text_splitter = text_splitter if isinstance(text_splitter, TextSplitter) else TextSplitter(**text_splitter) body = RecordCreateRequest( - title=title, + title=title or "", type=type, text_splitter=text_splitter, content=content,