diff --git a/assets/contributors.csv b/assets/contributors.csv index 03fece6232..2427c7a3cf 100644 --- a/assets/contributors.csv +++ b/assets/contributors.csv @@ -1,81 +1,82 @@ -author,company,github,linkedin,twitter,website -Jason Andrews,Arm,jasonrandrews,jason-andrews-7b05a8,, -Pareena Verma,Arm,pareenaverma,pareena-verma-7853607,, -Ronan Synnott,Arm,,ronansynnott,, -Florent Lebeau,Arm,,,, -Brenda Strech,Remote.It,bstrech,bstrech,@remote_it,www.remote.it -Liliya Wu,Arm,Liliyaw,liliya-wu-8b6227216,, -Julio Suarez,Arm,jsrz,juliosuarez,, -Gabriel Peterson,Arm,gabrieldpeterson,gabrieldpeterson,@gabedpeterson,https://corteximplant.com/@gabe -Christopher Seidl,Arm,,,, -Michael Hall,Arm,,,, -Kasper Mecklenburg,Arm,,,, -Mathias Brossard,Arm,,,, -Julie Gaskin,Arm,,,, -Pranay Bakre,Arm,,,, -Elham Harirpoush,Arm,,,, -Frédéric -lefred- Descamps,OCI,,,,lefred.be -Fr�d�ric -lefred- Descamps,OCI,,,,lefred.be -Kristof Beyls,Arm,,,, -David Spickett,Arm,,,, -Uma Ramalingam,Arm,uma-ramalingam,,, -Konstantinos Margaritis,VectorCamp,markos,konstantinosmargaritis,@freevec1,https://vectorcamp.gr/ -Diego Russo,Arm,diegorusso,diegor,diegor,https://www.diegor.it -Jonathan Davies,Arm,,,, -Zhengjun Xing,Arm,,,, -Leandro Nunes,Arm,,,, -Dawid Borycki,,dawidborycki,,, -Ying Yu,Arm,,,, -Bolt Liu,Arm,,,, -Roberto Lopez Mendez,Arm,,,, -Arnaud de Grandmaison,Arm,Arnaud-de-Grandmaison-ARM,arnauddegrandmaison,, -Jose-Emilio Munoz-Lopez,Arm,,,, -James Whitaker,Arm,,,, -Johanna Skinnider,Arm,,,, -Varun Chari,Arm,,,, -Adnan AlSinan,Arm,,,, -Graham Woodward,Arm,,,, -Basma El Gaabouri,Arm,,,, -Gayathri Narayana Yegna Narayanan,Arm,,,, -Alexandros Lamprineas,Arm,,,, -Annie Tallund,Arm,annietllnd,annietallund,, -Cyril Rohr,RunsOn,crohr,cyrilrohr,, -Rin Dobrescu,Arm,,,, -Przemyslaw Wirkus,Arm,PrzemekWirkus,przemyslaw-wirkus-78b73352,, -Nader Zouaoui,Day Devs,nader-zouaoui,nader-zouaoui,@zouaoui_nader,https://daydevs.com/ -Alaaeddine Chakroun,Day Devs,Alaaeddine-Chakroun,alaaeddine-chakroun,,https://daydevs.com/ -Koki Mitsunami,Arm,,kmitsunami,, -Chen Zhang,Zilliz,,,, -Tianyu Li,Arm,,,, -Georgios Mermigkis,VectorCamp,gMerm,georgios-mermigkis,,https://vectorcamp.gr/ -Ben Clark,Arm,,,, -Han Yin,Arm,hanyin-arm,nacosiren,, -Willen Yang,Arm,,,, -Daniel Gubay,,,,, -Paul Howard,,,,, -Iago Calvo Lista,Arm,,,, -Stephen Theobald,Arm,,,, -ThirdAI,,,,, -Preema Merlin Dsouza,,,,, -Dominica Abena O. Amanfo,,,,, -Arm,,,,, -Albin Bernhardsson,,,,, -Przemyslaw Wirkus,,,,, -Zach Lasiuk,,,,, -Daniel Nguyen,,,,, -Joe Stech,Arm,,,, -visualSilicon,,,,, -Konstantinos Margaritis,VectorCamp,,,, -Kieran Hejmadi,,,,, -Alex Su,,,,, -Chaodong Gong,,,,, -Owen Wu,Arm,,,, -Koki Mitsunami,,,,, -Nikhil Gupta,,,,, -Nobel Chowdary Mandepudi,Arm,,,, -Ravi Malhotra,Arm,,,, -Masoud Koleini,,,,, -Na Li,Arm,,,, -Tom Pilar,,,,, -Cyril Rohr,,,,, -Odin Shen,Arm,odincodeshen,odin-shen-lmshen,, \ No newline at end of file +author,company,github,linkedin,twitter,website +Jason Andrews,Arm,jasonrandrews,jason-andrews-7b05a8,, +Pareena Verma,Arm,pareenaverma,pareena-verma-7853607,, +Ronan Synnott,Arm,,ronansynnott,, +Florent Lebeau,Arm,,,, +Brenda Strech,Remote.It,bstrech,bstrech,@remote_it,www.remote.it +Liliya Wu,Arm,Liliyaw,liliya-wu-8b6227216,, +Julio Suarez,Arm,jsrz,juliosuarez,, +Gabriel Peterson,Arm,gabrieldpeterson,gabrieldpeterson,@gabedpeterson,https://corteximplant.com/@gabe +Christopher Seidl,Arm,,,, +Michael Hall,Arm,,,, +Kasper Mecklenburg,Arm,,,, +Mathias Brossard,Arm,,,, +Julie Gaskin,Arm,,,, +Pranay Bakre,Arm,,,, +Elham Harirpoush,Arm,,,, +Frédéric -lefred- Descamps,OCI,,,,lefred.be +Fr�d�ric -lefred- Descamps,OCI,,,,lefred.be +Kristof Beyls,Arm,,,, +David Spickett,Arm,,,, +Uma Ramalingam,Arm,uma-ramalingam,,, +Konstantinos Margaritis,VectorCamp,markos,konstantinosmargaritis,@freevec1,https://vectorcamp.gr/ +Diego Russo,Arm,diegorusso,diegor,diegor,https://www.diegor.it +Jonathan Davies,Arm,,,, +Zhengjun Xing,Arm,,,, +Leandro Nunes,Arm,,,, +Dawid Borycki,,dawidborycki,,, +Ying Yu,Arm,,,, +Bolt Liu,Arm,,,, +Roberto Lopez Mendez,Arm,,,, +Arnaud de Grandmaison,Arm,Arnaud-de-Grandmaison-ARM,arnauddegrandmaison,, +Jose-Emilio Munoz-Lopez,Arm,,,, +James Whitaker,Arm,,,, +Johanna Skinnider,Arm,,,, +Varun Chari,Arm,,,, +Adnan AlSinan,Arm,,,, +Graham Woodward,Arm,,,, +Basma El Gaabouri,Arm,,,, +Gayathri Narayana Yegna Narayanan,Arm,,,, +Alexandros Lamprineas,Arm,,,, +Annie Tallund,Arm,annietllnd,annietallund,, +Cyril Rohr,RunsOn,crohr,cyrilrohr,, +Rin Dobrescu,Arm,,,, +Przemyslaw Wirkus,Arm,PrzemekWirkus,przemyslaw-wirkus-78b73352,, +Nader Zouaoui,Day Devs,nader-zouaoui,nader-zouaoui,@zouaoui_nader,https://daydevs.com/ +Alaaeddine Chakroun,Day Devs,Alaaeddine-Chakroun,alaaeddine-chakroun,,https://daydevs.com/ +Koki Mitsunami,Arm,,kmitsunami,, +Chen Zhang,Zilliz,,,, +Tianyu Li,Arm,,,, +Georgios Mermigkis,VectorCamp,gMerm,georgios-mermigkis,,https://vectorcamp.gr/ +Ben Clark,Arm,,,, +Han Yin,Arm,hanyin-arm,nacosiren,, +Willen Yang,Arm,,,, +Daniel Gubay,,,,, +Paul Howard,,,,, +Iago Calvo Lista,Arm,,,, +Stephen Theobald,Arm,,,, +ThirdAI,,,,, +Preema Merlin Dsouza,,,,, +Dominica Abena O. Amanfo,,,,, +Arm,,,,, +Albin Bernhardsson,,,,, +Przemyslaw Wirkus,,,,, +Zach Lasiuk,,,,, +Daniel Nguyen,,,,, +Joe Stech,Arm,,,, +visualSilicon,,,,, +Konstantinos Margaritis,VectorCamp,,,, +Kieran Hejmadi,,,,, +Alex Su,,,,, +Chaodong Gong,,,,, +Owen Wu,Arm,,,, +Koki Mitsunami,,,,, +Nikhil Gupta,,,,, +Nobel Chowdary Mandepudi,Arm,,,, +Ravi Malhotra,Arm,,,, +Masoud Koleini,,,,, +Na Li,Arm,,,, +Tom Pilar,,,,, +Cyril Rohr,,,,, +Odin Shen,Arm,odincodeshen,odin-shen-lmshen,, +Avin Zarlez,Arm,AvinZarlez,avinzarlez,,https://www.avinzarlez.com/ diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/1-rag.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension/1-rag.md new file mode 100644 index 0000000000..53d9c27185 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/copilot-extension/1-rag.md @@ -0,0 +1,21 @@ +--- +title: RAG Overview +weight: 2 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## What is a RAG system? + +RAG stands for "Retrieval Augmented Generation". It describes an AI framework that combines information retrieval with text generation to improve the quality and accuracy of AI-generated content. + +The basic flow of a RAG system looks like this: + +1. Retrieval: The system searches a knowledge base, usually using some combination of vector and/or text search. +2. Augmentation: The retrieved information is then provided as context to a generative AI model to provide additional context for the user's query. +3. The AI model uses both the retrieved knowledge and its internal understanding to generate a more useful response to the user. + +The benefits of a RAG system revolve around improved factual accuracy of responses. It also allows a system to understand more up-to-date information, since you can add additional knowledge to the knowledge base much more easily than you could retrain the model. + +Most importantly, RAG lets you provide reference links to the user, showing the user where the system is getting its information. diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/2-vector.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension/2-vector.md new file mode 100644 index 0000000000..8400093bf1 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/copilot-extension/2-vector.md @@ -0,0 +1,160 @@ +--- +title: Vector Database +weight: 3 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## What is a Vector Database? + +A vector database is a specialized database designed to store and query vector representations of data. They are a crucial component of many AI applications. But what exactly are they, and how do they work? + +Traditional databases store data in tables or objects with defined attributes. However, they struggle to recognize similarities between data points that aren't explicitly defined. + +Vector databases, on the other hand, are designed to store a large numbers of vectors (arrays of numbers), and provide algorithms to be able to search through those stored vectors. That makes it much easier to identify similarities by comparing the vector locations in N dimensional space. This is typically done using distance metrics like cosine similarity or Euclidean distance. + +How can we convert complex ideas, like the semantic meaning of a series of words, into a series of of number based vectors? We do so using a process called embedding. + +### Embeddings + +Embeddings are vectors generated through an AI model. We can convert collections of "tokens" (word fragments) into a point in N dimensional space. + +Then for any given vector (like the embedding of a question asked by a user) we can query our vector database to find embedded data that is most similar. + +For our use case, we want to know which Arm learning path is most relevant to a question a user asks. + +First, ahead of time, we have to convert the raw data (Arm learning path content) into more consumable "chunks". In our case, small `yaml` files. Then we run those chunks through our LLM model and embed the content into our FAISS vector database. + +### FAISS + +FAISS (Facebook AI Similarity Search) is a library developed by Facebook AI Research that is designed to efficiently search for similar vectors in large datasets. FAISS is highly optimized for both memory usage and speed, making it the fastest similarity search algorithm available. + +One of the key reasons FAISS is so fast is its implementation of efficient Approximate Nearest Neighbor (ANN) search algorithms. ANN algorithms allow FAISS to quickly find vectors that are close to a given query vector without having to compare it to every single vector in the database. This significantly reduces the search time, especially in large datasets. + +Additionally, FAISS performs all searches in-memory, which means that it can leverage the full speed of the system's RAM. This in-memory search capability ensures that the search operations are extremely fast, as they avoid the latency associated with disk I/O operations. + +In our application, we can take the input from the user and embed it using the same model we used for our database. We then use FAISS nearest neighbor search to compare the user input to the nearest vectors in the database. We then look at the original chunk files for those closest vectors. Using the data from those `chunk.yaml` files, we can retrieve the Arm resource(s) most relevant for that user's question. + +The retrieved resources are then used to augment the context for the LLM, which generates a final response that is both contextually relevant and contains accurate information. + +### In Memory Deployment + +To ensure that our application scales efficiently, we will copy the FAISS database into every deployment instance. By deploying a static in-memory vector store in each instance, we eliminate the need for a centralized database, which can become a bottleneck as the number of requests increases. + +When each instance has its own copy of the FAISS database, it can perform vector searches locally, leveraging the full speed of the system's RAM. This approach ensures that the search operations are extremely fast and reduces the latency associated with network calls to a centralized database. + +Moreover, this method enhances the reliability and fault tolerance of our application. If one instance fails, others can continue to operate independently without being affected by the failure. This decentralized approach also simplifies the deployment process, as each instance is self-contained and does not rely on external resources for vector searches. + +By copying the FAISS database into every deployment, we achieve a scalable, high-performance solution that can handle a large number of requests efficiently. + +## Collecting Data into Chunks + +Arm has provided a [companion GitHub repo](https://github.com/ArmDeveloperEcosystem/python-rag-extension/) for this Learning Path that serves as a Python-based Copilot RAG Extension example. In this repo, we have provided scripts to convert an Arm learning path into a series of `chunk.yaml` files for use in our RAG application. + +### Clone the GitHub repository + +To clone the repo, run + +```bash +git clone https://github.com/ArmDeveloperEcosystem/python-rag-extension.git +``` + +### Chunk Creation Script Set up + +Navigate to the `vectorstore` folder in the [python-rag-extension github repo](https://github.com/ArmDeveloperEcosystem/python-rag-extension/) you just cloned. + +```bash +cd python-rag-extension/vectorstore +``` + +It is recommended to use a virtual environment to manage dependencies. + +Ensure you have `conda` set up in your development environment. If you aren't sure how, you can follow this [Installation Guide](https://docs.anaconda.com/miniconda/install/). + +To create a new conda environment, use the following command: + +```sh +conda create --name vectorstore python=3.11 +``` + +Once set up is complete, activate the new environment: + +```sh +conda activate vectorstore +``` + +Install the required packages: + +```sh +conda install --file vectorstore-requirements.txt +``` + +### Generate Chunk Files + +To generate chunks, use the following command: + +```sh +python chunk_a_learning_path.py --url +``` + +Replace `` with the URL of the learning path you want to process. If no URL is provided, the script will default to a [known learning path URL](https://learn.arm.com/learning-paths/cross-platform/kleidiai-explainer). + +The script will process the specified learning path and save the chunks as YAML files in a `./chunks/` directory. + +## Combine Chunks into FAISS index + +Once you have a `./chunks/` directory full of yaml files, we now need to use FAISS to create our vector database. + +### OpenAI Key and Endpoint + +Ensure your local environment has your `AZURE_OPENAI_KEY` and `AZURE_OPENAI_ENDPOINT` set. + +#### If needed, generate Azure OpenAI keys and deployment + +1. **Create an OpenAI Resource**: + - Go to the [Azure Portal](https://portal.azure.com/). + - Click on "Create a resource". + - Search for "OpenAI" and select "Azure OpenAI Service". + - Click "Create". + +1. **Configure the OpenAI Resource**: + - Fill in the required details such as Subscription, Resource Group, Region, and Name. + - Click "Review + create" and then "Create" to deploy the resource. + +1. **Generate API Key and Endpoint**: + - Once the resource is created, navigate to the resource page. + - Under the "Resource Management->Keys and Endpoint" section, you will find the key and endpoint values. + - Copy these values and set them in your local environment. + + ```sh + export AZURE_OPENAI_KEY="" + export AZURE_OPENAI_ENDPOINT="https://.openai.azure.com/" + ``` + + You now have the necessary keys to use Azure OpenAI in your application. + +1. **Deploy text-embedding-ada-002 model** + - Go inside Azure AI Foundry for your new deployment + - Under "Deployments", ensure you have a deployment for "text-embedding-ada-002" + +### Generate Vector Database Files + +Run the python script to create the FAISS index `.bin` and `.json` files. + +**NOTE:** This assumes the chunk files are located in a `chunks` subfolder, as they should automatically be. + +```bash +python local_vectorstore_creation.py +``` + +Copy the generated `bin` and `json` files to the root directory of your Flask application. + +They should be in the `vectorstore/chunks` folder. Since you are likely still in the `vectorstore` folder, run this command to copy: + +```bash +cp chunks/faiss_index.bin ../ +cp chunks/metadata.json ../ +``` + +Your vector database is now ready for your flask application. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/3-github-app.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension/3-github-app.md new file mode 100644 index 0000000000..b15f12b633 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/copilot-extension/3-github-app.md @@ -0,0 +1,43 @@ +--- +title: Create GitHub Application +weight: 4 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +Now we need to create a Copilot extension on GitHub to connect to our deployed application. + +## Create a GitHub app + +> For the most up to date instructions, follow the [official documentation for creating a GitHub App for Copilot Extension](https://docs.github.com/en/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension#creating-a-github-app). + +On any page of [GitHub](https://github.com/), click your profile picture and go to Settings. Scroll down to developer settings, and go to [create a GitHub App](https://github.com/settings/apps). + +![Create GitHub Application screen](images/githubapp-create.png) + +Your GitHub App must have: + - A name + - A homepage URL + - Make sure Webhook -> Active is deselected + +![GitHub App name and URL](images/githubapp-name.png) +![Webhook deselected](images/githubapp-deselected.png) + +The rest can be the default values. + +Scroll to the bottom and click "Create GitHub App" + +## Get Client ID and Secret + +After you create your app, open it up. You will see listed your Client ID under General -> About. + +![Client ID and Secret](images/githubapp-clientid.png) + +Under that is **Client Secrets**, click "Generate a new client secret" and save the value. Make sure you copy it before it goes away, you will need it for the next step as part of the flask application. + +## Install Application + +Click **Install App** in the sidebar, then install your app onto your account. + +![Install](images/githubapp-install.png) diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/4-flask.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension/4-flask.md new file mode 100644 index 0000000000..d7715738cf --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/copilot-extension/4-flask.md @@ -0,0 +1,222 @@ +--- +title: Build a RAG System +weight: 5 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## How do I implement RAG in Flask? + +In the [Build a GitHub Copilot Extension in Python](learning-paths/servers-and-cloud-computing/gh-copilot-simple/) Learning Path, you created a simple Copilot Extension in Python. Here, you'll add RAG functionality to that Flask app. + +You already generated a vector store in a previous section, which you will use as the knowledge base for your RAG retrieval. + +As you saw in the [Build a GitHub Copilot Extension in Python](learning-paths/servers-and-cloud-computing/gh-copilot-simple/) Learning Path, the `/agent` endpoint is what GitHub will invoke to send a query to your Extension. + +There are a minimum of two things you must add to your existing Extension to obtain RAG functionality: + +1. Vector search functions, to find context from your knowledge base. +2. A system prompt that instructs your system about how to use the context from your knowledge base. + +### Vector search + +First, import necessary Python packages: + +```Python +import faiss +import json +import requests +import numpy as np +``` + +Then create functions to load the FAISS index that you previously created, and invoke them: + +```Python +def load_faiss_index(index_path: str): + """Load the FAISS index from a file.""" + print(f"Loading FAISS index from {index_path}") + index = faiss.read_index(index_path) + print(f"Loaded index containing {index.ntotal} vectors") + return index + +def load_metadata(metadata_path: str): + """Load metadata from a JSON file.""" + print(f"Loading metadata from {metadata_path}") + with open(metadata_path, 'r') as f: + metadata = json.load(f) + print(f"Loaded metadata for {len(metadata)} items") + return metadata + +FAISS_INDEX = load_faiss_index("faiss_index.bin") +FAISS_METADATA = load_metadata("metadata.json") +``` + +You put these objects in global variables so they stay in memory persistently. + +After this, create the functions to make embeddings and search embeddings: + +```Python +def create_embedding(query: str, headers=None): + print(f"Creating embedding using model: {MODEL_NAME}") + copilot_req = { + "model": MODEL_NAME, + "input": [query] + } + r = requests.post(llm_client, json=copilot_req, headers=headers) + r.raise_for_status() + return_dict = r.json() + + return return_dict['data'][0]['embedding'] + + +def embedding_search(query: str, k: int = 5, headers=None): + """ + Search the FAISS index with a text query. + + Args: + query (str): The text to search for. + k (int): The number of results to return. + + Returns: + list: A list of dictionaries containing search results with distances and metadata. + """ + print(f"Searching for: '{query}'") + # Convert query to embedding + query_embedding = create_embedding(query, headers) + query_array = np.array(query_embedding, dtype=np.float32).reshape(1, -1) + + # Perform the search + distances, indices = FAISS_INDEX.search(query_array, k) + print(distances, indices) + # Prepare results + results = [] + for i, (dist, idx) in enumerate(zip(distances[0], indices[0])): + if idx != -1: # -1 index means no result found + if float(dist) < DISTANCE_THRESHOLD: + result = { + "rank": i + 1, + "distance": float(dist), + "metadata": FAISS_METADATA[idx] + } + results.append(result) + + return results +``` + +The context for these functions can be found in the [vectorstore_functions.py](https://github.com/ArmDeveloperEcosystem/python-rag-extension/blob/main/utils/vectorstore_functions.py) file. + +### System Prompt + +A crucial part of any RAG system is constructing the prompt containing the knowledge base context. First, create the base system prompt: + +```Python +# change this System message to fit your application +SYSTEM_MESSAGE = """You are a world-class expert in [add your extension field here]. These are your capabilities, which you should share with users verbatim if prompted: + +[add your extension capabilities here] + +Below is critical information selected specifically to help answer the user's question. Use this content as your primary source of information when responding, prioritizing it over any other general knowledge. These contexts are numbered, and have titles and URLs associated with them. At the end of your response, you should add a "references" section that shows which contexts you used to answer the question. The reference section should be formatted like this: + +References: + +* [precise title of Context 1 denoted by TITLE: below](URL of Context 1) +* [precise title of Context 2 denoted by TITLE: below](URL of Context 2) + +etc. +Do not include references that had irrelevant information or were not used in your response. + +Contexts:\n\n +""" +``` + +Next, call your embedding search function, and add the context to your system prompt: + +```Python +results = vs.embedding_search(user_message, amount_of_context_to_use, headers) +results = vs.deduplicate_urls(results) + +context = "" +for i, result in enumerate(results): + context += f"CONTEXT {i+1}\nTITLE:{result['metadata']['title']}\nURL:{result['metadata']['url']}\n\n{result['metadata']['original_text']}\n\n" + print(f"url: {result['metadata']['url']}") + +system_message = [{ + "role": "system", + "content": system_message + context +}] +``` + +Once the system message is built, add it to the original message to create `full_prompt_messages` and invoke the copilot endpoint: + +```Python +copilot_req = { + "model": model_name, + "messages": full_prompt_messages, + "stream": True +} + +chunk_template = sm.get_chunk_template() +r = requests.post(llm_client, json=copilot_req, headers=headers, stream=True) +r.raise_for_status() +stream = r.iter_lines() +``` + +You can then stream the response back to GitHub. + +The context for this code can be found in the [agent_functions.py](https://github.com/ArmDeveloperEcosystem/python-rag-extension/blob/main/utils/agent_functions.py) file. + +### Marketplace endpoint (optional, but needed to obtain marketplace events) + +If you publish your extension to the marketplace, you can get responses back when users install/uninstall your extension. + +You can write these to the database of your choice for better aggregation, but here is a simple version that writes each invocation to a local json file: + +```Python +@app.route('/marketplace', methods=['POST']) +def marketplace(): + payload_body = request.get_data() + print(payload_body) + + # Verify request has JSON content + if not request.is_json: + return jsonify({ + 'error': 'Content-Type must be application/json' + }), 415 + + try: + # Get JSON payload + payload = request.get_json() + + # Print the payload + print("Received payload:") + print(json.dumps(payload, indent=2)) + + output_dir = Path('marketplace_events') + + # Generate unique filename and save + filename = f"{uuid.uuid4().hex}.json" + file_path = output_dir / filename + + with open(file_path, 'w') as f: + json.dump(payload, f, indent=2) + + print(f"Saved payload to {file_path}") + + return jsonify({ + 'status': 'success', + 'message': 'Event received and processed', + 'file_path': str(file_path) + }), 201 + + except Exception as e: + return jsonify({ + 'error': f'Failed to process request: {str(e)}' + }), 500 +``` + +Before running this function, ensure that the `marketplace_events` directory is created in your root directory (where the main flask file is). + +The context for this code can be found in the [flask_app.py](https://github.com/ArmDeveloperEcosystem/arm-gh-copilot-extension/blob/main/flask_app.py) file. + +Once these elements are in place, you are ready to deploy your app. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/5-deployment.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension/5-deployment.md new file mode 100644 index 0000000000..149980b05f --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/copilot-extension/5-deployment.md @@ -0,0 +1,24 @@ +--- +title: Infrastructure Deployment +weight: 6 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## How do I deploy my Copilot RAG Extension? + +You can deploy on whatever cloud infrastructure you'd like to use. These are the suggested requirements: + +1. A domain that you own with DNS settings that you control +2. A load balancer +3. An auto-scaling cluster in a private virtual cloud subnet that you can adjust the size of based on load + +Arm has provided a Copilot Extension deployment Learning Path for AWS, called [Graviton Infrastructure for GitHub Copilot Extensions](../copilot-extension-deployment/). + +Whatever method you use to deploy your Extension, make note of the final endpoint URLs, specifically + +* `/agent` (required) +* `/marketplace` (optional, but needed to obtain marketplace events) + +These are the endpoints that you will need full URLs for to configure your GitHub application. diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/6-github-configure.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension/6-github-configure.md new file mode 100644 index 0000000000..e313399a5b --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/copilot-extension/6-github-configure.md @@ -0,0 +1,41 @@ +--- +title: Configure GitHub Application +weight: 7 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +Now we need to configure the GitHub Application we created before to connect to our deployed Copilot extension application. + +## Configure GitHub App for Copilot Extension + +> For the most up to date instructions, follow the [official documentation for configuring your GitHub App for Copilot Extension](https://docs.github.com/en/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-extension#configuring-your-github-app). + +On any page of [GitHub](https://github.com/), click your profile picture and go to Settings. Scroll down to developer settings, and open the GitHub App we made previously. + +Make the following changes: + +### In the "General" settings + +In the "Callback URL" field, put the callback URL of your agent that you deployed in the previous step. + +**Note:** If you are not using a deployed application and you want to test locally, you can use an ephemeral domain in ngrok. However you will need to update this URL every time you restart your ngrok server. + +### In the "Permissions & events" settings + +Under "Account permissions", grant read-only permissions to "GitHub Copilot Chat". + +![Account Permissions](images/githubconfig-permissions.png) + +### In the "Copilot" settings + +Set your app type to "Agent," then fill out the remaining fields. + +Under "URL," enter your server's hostname (aka forwarding endpoint) that you deployed in the previous step. + +### Optional: add your marketplace endpoint + +If you would like to get install/uninstall events when users interact with your marketplace posting, set up a webhook. Under the 'general' tab of your application settings, activate the webhook and add your marketplace endpoint: + +![Webhook setup](images/marketplace.png) \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/7-testing.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension/7-testing.md new file mode 100644 index 0000000000..c12586941d --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/copilot-extension/7-testing.md @@ -0,0 +1,30 @@ +--- +title: Test the installation +weight: 8 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Chat with your extension + +After you update your GitHub App settings, you can start chatting with your extension by typing @YOUR-EXTENSION-NAME in the Copilot Chat window, followed by your prompt: + +![Test the extension](images/extension-test.png) + + +## Optional: Publish your extension on the marketplace + +> For the most up to date instructions, follow the [official documentation for listing your extension on the marketplace](https://docs.github.com/en/copilot/building-copilot-extensions/managing-the-availability-of-your-copilot-extension#listing-your-copilot-extension-on-the-github-marketplace). + +## Enhancements + +There are many enhancements you can make to your extension, including inserting your own hard-coded links, etc into the response stream. + +Another possibility is adding another copilot invocation to rephrase the previous conversation prior to your main copilot invocation. This yields more robust results, if users reference previous elements of the conversation in their question. + +You can precisely tailor your RAG extension to your use case, to make your extension as useful as possible. + +## Conclusion + +Congratulations on completing this learning path! By following the steps and processes you learned here, you can now create your own powerful and customized Copilot extensions to enhance your development workflow. diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/_index.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension/_index.md new file mode 100644 index 0000000000..e7b54be90a --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/copilot-extension/_index.md @@ -0,0 +1,46 @@ +--- +title: Create a RAG-based GitHub Copilot Extension in Python + +minutes_to_complete: 30 + +who_is_this_for: This is an advanced topic for software developers who want to learn how to build a Retrieval Augmented Generation (RAG) based GitHub Copilot Extension. + +learning_objectives: + - Explain what a RAG system is. + - Create vector embeddings for a RAG knowledge base. + - Implement RAG in a Copilot Extension. + - Configure a GitHub Copilot Extension for your RAG application. + +prerequisites: + - The [Build a GitHub Copilot Extension in Python](../gh-copilot-simple/) Learning Path. + - The [Graviton Infrastructure for GitHub Copilot Extensions](../copilot-extension-deployment/) Learning Path. + - A GitHub account. + - A Linux-based computer with Python installed. + +author: + - Avin Zarlez + - Joe Stech + +### Tags +cloud_service_providers: AWS +skilllevels: Advanced +subjects: ML +armips: + - Neoverse +tools_software_languages: + - Python + - FAISS + - GitHub + - conda + - AWS CDK +operatingsystems: + - Linux + - MacOS + + +### FIXED, DO NOT MODIFY +# ================================================================================ +weight: 1 # _index.md always has weight of 1 to order correctly +layout: "learningpathall" # All files under learning paths have this same wrapper +learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/_next-steps.md b/content/learning-paths/servers-and-cloud-computing/copilot-extension/_next-steps.md new file mode 100644 index 0000000000..b708fce39b --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/copilot-extension/_next-steps.md @@ -0,0 +1,23 @@ +--- + +further_reading: + - resource: + title: GitHub Marketplace for Copilot extensions + link: https://github.com/marketplace?type=apps&copilot_app=true/ + type: website + - resource: + title: About building Copilot Extensions + link: https://docs.github.com/en/copilot/building-copilot-extensions/about-building-copilot-extensions/ + type: documentation + - resource: + title: Copilot Extensions repository + link: https://github.com/copilot-extensions/ + type: documentation + +# ================================================================================ +# FIXED, DO NOT MODIFY +# ================================================================================ +weight: 21 # set to always be larger than the content in this path, and one more than 'review' +title: "Next Steps" # Always the same +layout: "learningpathall" # All files under learning paths have this same wrapper +--- diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/extension-test.png b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/extension-test.png new file mode 100644 index 0000000000..7b8537b318 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/extension-test.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-clientid.png b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-clientid.png new file mode 100644 index 0000000000..2d801638a4 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-clientid.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-create.png b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-create.png new file mode 100644 index 0000000000..957efc2dd7 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-create.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-deselected.png b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-deselected.png new file mode 100644 index 0000000000..31dde674a9 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-deselected.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-install.png b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-install.png new file mode 100644 index 0000000000..9a4af01a34 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-install.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-name.png b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-name.png new file mode 100644 index 0000000000..551eece22a Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubapp-name.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubconfig-makepublic.png b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubconfig-makepublic.png new file mode 100644 index 0000000000..ff10cb5c7d Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubconfig-makepublic.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubconfig-permissions.png b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubconfig-permissions.png new file mode 100644 index 0000000000..0bdd40aab1 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/githubconfig-permissions.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/marketplace.png b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/marketplace.png new file mode 100644 index 0000000000..4c523e1753 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/copilot-extension/images/marketplace.png differ