diff --git a/oci-langchain-dac-lab/.gitignore b/oci-langchain-dac-lab/.gitignore new file mode 100644 index 000000000..e87742515 --- /dev/null +++ b/oci-langchain-dac-lab/.gitignore @@ -0,0 +1,21 @@ +src/terraform/.terraform +src/terraform/provider.tf +src/terraform/env.tf +src/function/command.md +src/helidon +src/target +tfstate.tf +ssh_key_starter +ssh_key_starter.pub +target +helper +variables.sh +env.sh +output +option/src/app/dotnet/src/obj +option/src/app/dotnet_mysql/src/obj +option/src/app/java_helidon/target +option/src/app/java_helidon_mysql/target +option/src/app/java_springboot/target +option/src/app/fn/fn_java/target +.DS_Store diff --git a/oci-langchain-dac-lab/0-intro/images/agent-architecture.png b/oci-langchain-dac-lab/0-intro/images/agent-architecture.png new file mode 100644 index 000000000..37617f6dd Binary files /dev/null and b/oci-langchain-dac-lab/0-intro/images/agent-architecture.png differ diff --git a/oci-langchain-dac-lab/0-intro/images/lg-agent-react.png b/oci-langchain-dac-lab/0-intro/images/lg-agent-react.png new file mode 100644 index 000000000..5acc3c5b2 Binary files /dev/null and b/oci-langchain-dac-lab/0-intro/images/lg-agent-react.png differ diff --git a/oci-langchain-dac-lab/0-intro/images/lg-screenshot.png b/oci-langchain-dac-lab/0-intro/images/lg-screenshot.png new file mode 100644 index 000000000..392d8839d Binary files /dev/null and b/oci-langchain-dac-lab/0-intro/images/lg-screenshot.png differ diff --git a/oci-langchain-dac-lab/0-intro/images/oda-agent-definition.png b/oci-langchain-dac-lab/0-intro/images/oda-agent-definition.png new file mode 100644 index 000000000..2d8266809 Binary files /dev/null and b/oci-langchain-dac-lab/0-intro/images/oda-agent-definition.png differ diff --git a/oci-langchain-dac-lab/0-intro/images/oda-agent-llm.png b/oci-langchain-dac-lab/0-intro/images/oda-agent-llm.png new file mode 100644 index 000000000..6e16fb796 Binary files /dev/null and b/oci-langchain-dac-lab/0-intro/images/oda-agent-llm.png differ diff --git a/oci-langchain-dac-lab/0-intro/images/physical-architecture.png b/oci-langchain-dac-lab/0-intro/images/physical-architecture.png new file mode 100644 index 000000000..7bbdde150 Binary files /dev/null and b/oci-langchain-dac-lab/0-intro/images/physical-architecture.png differ diff --git a/oci-langchain-dac-lab/0-intro/intro.md b/oci-langchain-dac-lab/0-intro/intro.md new file mode 100644 index 000000000..e2bda3902 --- /dev/null +++ b/oci-langchain-dac-lab/0-intro/intro.md @@ -0,0 +1,74 @@ +# Introduction + +## About This Workshop +In this workshop, you will learn how to build AI agents using LangChain and LangGraph. + +You will progressively build agents using: +- Python +- LangChain or LangGraph +- an on-demand large language model (LLM) +- or a Dedicated AI Cluster (DAC) to import open-weight models from Hugging Face. + - See https://docs.oracle.com/en-us/iaas/Content/generative-ai/imported-models.htm. + - For example, models include Alibaba Qwen, DeepSeek, Google Gemma, Meta Llama, Microsoft Phi, MiniMax, Mistral, Moonshot AI Kimi, NVIDIA Nemotron, OpenAI Whisper, OpenAI GptOss, and Z.ai GLM. + +The installation requirements for this lab are minimal. Everything is done in OCI Cloud Editor. + +Estimated Workshop Time: 60 minutes + +### What You Will Learn + +In these labs, you will get an introduction to how to: +- Connect LangChain or LangGraph to OCI +- Build systems ranging from simple agents to multi-agent systems + +![Screenshot](images/lg-screenshot.png =50%x*) + +### What is an Agent + +**Definition of AI Agent:**: +- An AI Agent interacts autonomously with its environment. It uses tools and data to perform self-determined tasks to meet predetermined goals.  + +![Definition](images/oda-agent-definition.png =50%x*) + +Unlike a traditional program, an AI agent determines which steps and actions to take to achieve a goal. + +In practice, an AI agent has: +- **Tools** +- **Data** + +that it can use. It decides which tool or data to use to achieve the **goal** and produce the desired **result**. At the core of an agent is a large language model. During the lab, we will use either an on-demand model or a Dedicated AI Cluster (DAC). + +![LLM](images/oda-agent-llm.png =50%x*) + +### Logical Architecture + +This LiveLab covers several AI-agent architectures. +- First, **a single agent** with tools and data. +- **A ReAct agent** that combines step-by-step reasoning with external tool use to solve complex tasks. + +![Agent](images/lg-agent-react.png =50%x*) + +We will then explore more complex architectures, including memory, and several multi-agent systems. +- **Reflection** +- **Human in the loop** +- **Supervisor**, .... + +![MultiAgent](images/agent-architecture.png =50%x*) + +### Physical Architecture + +The physical architecture consists primarily of LangChain Agents, which call Python functions or REST APIs to access tools. +In the lab, we keep the setup as simple as possible by using dummy tools to avoid dependencies. + +![Physical Architecture](images/physical-architecture.png =50%x*) + +### Objectives + +- Import all the samples and test them + +**Please proceed to the [next lab.](#next)** + +## Acknowledgements + +- **Author** + - Marc Gueury, AI Applied Engineer diff --git a/oci-langchain-dac-lab/1-install/images/api_key1.png b/oci-langchain-dac-lab/1-install/images/api_key1.png new file mode 100755 index 000000000..72f87d282 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/api_key1.png differ diff --git a/oci-langchain-dac-lab/1-install/images/api_key2.png b/oci-langchain-dac-lab/1-install/images/api_key2.png new file mode 100755 index 000000000..f5df6af37 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/api_key2.png differ diff --git a/oci-langchain-dac-lab/1-install/images/api_key3.png b/oci-langchain-dac-lab/1-install/images/api_key3.png new file mode 100755 index 000000000..4a85226ec Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/api_key3.png differ diff --git a/oci-langchain-dac-lab/1-install/images/chicago-region.png b/oci-langchain-dac-lab/1-install/images/chicago-region.png new file mode 100755 index 000000000..0282242b8 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/chicago-region.png differ diff --git a/oci-langchain-dac-lab/1-install/images/cloud-shell-public-network.png b/oci-langchain-dac-lab/1-install/images/cloud-shell-public-network.png new file mode 100755 index 000000000..b0ce5b966 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/cloud-shell-public-network.png differ diff --git a/oci-langchain-dac-lab/1-install/images/compartment1.png b/oci-langchain-dac-lab/1-install/images/compartment1.png new file mode 100755 index 000000000..826045e4f Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/compartment1.png differ diff --git a/oci-langchain-dac-lab/1-install/images/compartment2.png b/oci-langchain-dac-lab/1-install/images/compartment2.png new file mode 100755 index 000000000..fc58d9f36 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/compartment2.png differ diff --git a/oci-langchain-dac-lab/1-install/images/dac0.png b/oci-langchain-dac-lab/1-install/images/dac0.png new file mode 100755 index 000000000..22624c678 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/dac0.png differ diff --git a/oci-langchain-dac-lab/1-install/images/dac1.png b/oci-langchain-dac-lab/1-install/images/dac1.png new file mode 100755 index 000000000..2943c1129 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/dac1.png differ diff --git a/oci-langchain-dac-lab/1-install/images/dac2.png b/oci-langchain-dac-lab/1-install/images/dac2.png new file mode 100755 index 000000000..19342243a Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/dac2.png differ diff --git a/oci-langchain-dac-lab/1-install/images/dac3.png b/oci-langchain-dac-lab/1-install/images/dac3.png new file mode 100755 index 000000000..e2e84cd43 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/dac3.png differ diff --git a/oci-langchain-dac-lab/1-install/images/dac4.png b/oci-langchain-dac-lab/1-install/images/dac4.png new file mode 100755 index 000000000..d0aaeb7db Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/dac4.png differ diff --git a/oci-langchain-dac-lab/1-install/images/hugging-face1.png b/oci-langchain-dac-lab/1-install/images/hugging-face1.png new file mode 100755 index 000000000..8c68c7586 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/hugging-face1.png differ diff --git a/oci-langchain-dac-lab/1-install/images/hugging-face2.png b/oci-langchain-dac-lab/1-install/images/hugging-face2.png new file mode 100755 index 000000000..c2269b3f0 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/hugging-face2.png differ diff --git a/oci-langchain-dac-lab/1-install/images/imported-model1.png b/oci-langchain-dac-lab/1-install/images/imported-model1.png new file mode 100755 index 000000000..2ec3dd8b7 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/imported-model1.png differ diff --git a/oci-langchain-dac-lab/1-install/images/policy-create.png b/oci-langchain-dac-lab/1-install/images/policy-create.png new file mode 100755 index 000000000..54c2aa252 Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/policy-create.png differ diff --git a/oci-langchain-dac-lab/1-install/images/policy-menu.png b/oci-langchain-dac-lab/1-install/images/policy-menu.png new file mode 100755 index 000000000..f1cc6720c Binary files /dev/null and b/oci-langchain-dac-lab/1-install/images/policy-menu.png differ diff --git a/oci-langchain-dac-lab/1-install/install.md b/oci-langchain-dac-lab/1-install/install.md new file mode 100755 index 000000000..6e940b75f --- /dev/null +++ b/oci-langchain-dac-lab/1-install/install.md @@ -0,0 +1,216 @@ +# Install the components + +## Introduction +In this lab, you will prepare OCI to use Generative AI and Large Language Models (LLMs). + +Optionally, you will import an open-weight model into a Dedicated AI Cluster (DAC). + +DAC-hosted models run on dedicated infrastructure in your tenancy. Use a DAC-hosted model when you need production-grade control over model hosting and inference. DACs provide flexibility, isolation, predictable latency, fine-tuning support, cost efficiency at scale, deployment near data, and simplified management. + +Estimated time: 30 min + +### Objectives + +- Configure OCI Generative AI access. + +### Prerequisites + +- An OCI account with sufficient credits for completing the lab. (Some of the services used in this lab are not part of the *Always Free* program.) +- Check that your tenancy has access to a Generative AI region, such as **Frankfurt, London, Chicago, Abu Dhabi, Riyadh, or Osaka**. See the full list here: https://docs.oracle.com/en-us/iaas/Content/generative-ai/regions.htm + - **For Paid Tenancy** + - Click the region selector at the top of the screen. + - Check that your tenancy is subscribed to one of the above regions. + - If not, click **Manage Regions** to add it to your regions list. You need tenancy administrator rights for this. + - For example, click on the US Midwest (Chicago). + - Click **Subscribe**. + + ![Chicago Region](images/chicago-region.png) + + - **For Free Trial**, the home region should be one where Generative AI On Demand is available. +- This lab uses Cloud Shell with Public Network access. + + The lab assumes that you have access to OCI Cloud Shell with Public Network access. + To check whether you have it, start Cloud Shell. You should see **Network: Public** at the top. If not, try changing to **Public Network**. If it works, there is nothing else to do. + ![Cloud Shell Public Network](images/cloud-shell-public-network.png) + + OCI administrators have this permission automatically, or your administrator may have already added the required policy. + - **Solution:** + + If not, ask your administrator to follow this document: + + https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cloudshellintro_topic-Cloud_Shell_Networking.htm#cloudshellintro_topic-Cloud_Shell_Public_Network + + They need to add a policy to your tenancy: + + ``` + + allow group to use cloud-shell-public-network in tenancy + + ``` + +## Task 1: Prepare to save configuration settings + +1. Open a text editor and copy and paste this text into a file on your local computer. These are the variables used during the lab. + + ``` + + List of ##VARIABLES## + ===================== + REGION=(SAMPLE) eu-frankfurt-1 + COMPARTMENT_OCID=(SAMPLE) ocid1.compartment.oc1.xxxxxxx + api-key1=(SAMPLE) sk-xxxxxxxxxxxxxx + api-key2=(SAMPLE) sk-xxxxxxxxxxxxxx + OBJECT_STORAGE_NAME=(SAMPLE) bucket-123456 + OPENWEATHER_API_KEY=(SAMPLE) xxxxxx + + Optional + ======== + hugging-face-token=(SAMPLE) hf_xxxxxxxxxxxxxxxxxxxx + BASE_URL=(sample) https://inference.generativeai.eu-frankfurt-1.oci.oraclecloud.com/openai/v1/chat/completions + GENAI_DAC_ENDPOINT_OCID=(SAMPLE) ocid1.generativeaiendpoint.oc1.xxxxxxxxxx + + + + ----------------------------------------------------------------------- + + ``` + +## Task 2: Create a Compartment + +The compartment will be used to contain all the components of the lab. + +You can: +- Use an existing compartment to run the lab. +- Create a new one (recommended). + +1. Log in to your OCI account/tenancy. +2. Double-check that you are in a region with GenAI available. +3. Go to the 3-bar/hamburger menu of the console, then Identity & Security > Compartments. + ![Menu Compartment](images/compartment1.png) +4. Click ***Create Compartment***. + - Give it a name, for example, ***VIBE-AI***. + - Click ***Create Compartment*** again. + ![Create Compartment](images/compartment2.png) +5. When the compartment is created, copy the compartment OCID, ##COMPARTMENT_OCID##, and add it to your notes. + +## Task 3: Create a Policy + +- Go to the OCI Console menu and choose *Identity & Security* / *Policies*. + ![Policy Menu](images/policy-menu.png) +- Click *Create Policy*. +- Name: *policy-vibe* +- Description: *policy-vibe* +- Click *Show Manual editor*. +- Copy the following, replacing ##COMPARTMENT\_OCID## with your value: + ``` + allow any-user to manage generative-ai-family in compartment id ##COMPARTMENT_OCID## + ``` +- Click *Create*. + ![Policy Create](images/policy-create.png) + +## Task 4: Create an API Key - Optional + +First, create an OpenAI-compatible API key. +1. Log in to the OCI Console. Record the region name in your notes as ##REGION##. You should be in a region with Generative AI. See the full list here: https://docs.oracle.com/en-us/iaas/Content/generative-ai/regions.htm +2. Click the hamburger menu / AI & Analytics / Generative AI. + + ![API_KEY](images/api_key1.png) + +3. Go to **API Keys** on the right side. +4. Click **Create API key**. + + ![API_KEY](images/api_key2.png) + +5. Fill in the following: + - Name: **api-key** + - Key one name: **api-key1** + - Key one expiration date: **7/20/2030** (a date far in the future) + - Key two name: **api-key2** + - Key two expiration date: **7/20/2030** (a date far in the future) + - Click *Create*. + + ![API_KEY](images/api_key3.png) + +6. Copy the values of the two keys in your notes (##api-key1##, ##api-key2##). + - api-key1=sk-xxxxxxxxx + - api-key2=sk-xxxxxxxxx + - Click **Close**. +Although you can choose any model from any provider to continue the lab, this guide covers several models available in OCI. + +7. Note, if you use a API Key the policy defined above can be more specific like this: + + ``` + allow any-user to manage generative-ai-family in compartment id ##COMPARTMENT_OCID## where request.principal.type = 'generativeaiapikey' + ``` + +## Task 5: Install a Dedicated AI Cluster (DAC) - Optional + +⚠️ This optional task starts a GPU for at least one hour, so it may cost several euros per hour. Do not forget to stop the DAC after testing. + +We will follow this process: https://docs.oracle.com/en-us/iaas/Content/generative-ai/imported-models.htm + +DAC-hosted models run on dedicated infrastructure in your tenancy. Use a DAC-hosted model when you need production-grade control over model hosting and inference. DACs provide several advantages: + +- **Flexibility:** Import supported Hugging Face-format models from Hugging Face or Object Storage, test imported models with shorter commitments, choose fine-tuned or quantized versions, and right-size based on visible hardware specifications. +- **Isolation:** Run workloads on dedicated GPU resources inside your tenancy, which helps protect sensitive data, avoids shared-resource contention, and supports regulated workloads. +- **Predictable latency:** Dedicated infrastructure can provide more stable time-to-first-token and inference response times than shared model endpoints, especially for scaling production applications. +- **Fine-tuning support:** Host fine-tuned models alongside base models, run multiple fine-tuned models on a single cluster, and control model lifecycle and upgrade cadence. +- **Cost efficiency at scale:** For inference-heavy workloads, DACs can reduce effective price per token by keeping dedicated resources highly utilized and hosting multiple models on one cluster. +- **Deployment near data:** Deploy in supported OCI regions, including regulated regions where available, to support data residency, lower latency, and simpler security reviews. +- **Simplified management:** OCI manages the infrastructure while you manage model deployment, scaling, fine-tuning, and application integration. + +Documentation: https://docs.oracle.com/en-us/iaas/Content/generative-ai/import-model-from-hugging-face.htm#top + +1. Create a Hugging Face token. + - Open https://huggingface.co/ in your browser. + - Log in or sign up. + - Go to Hugging Face / Settings / Access Tokens. + - Click **Create new token**. + ![Hugging face](images/hugging-face1.png) + - Use either a read token (easier) or, preferably for production, a fine-grained token scoped to the model repository. + - Copy the token into your notes as ##hugging-face-token##. + ![Hugging face](images/hugging-face2.png) +2. In OCI Console, go to Analytics & AI / Generative AI / Imported models. +3. Click **Create Imported model**. + ![imported model](images/imported-model1.png) +4. Enter model metadata: + - Available models may differ by the time you complete this lab. Choose the model that best suits your needs. This lab uses the following NVIDIA model: https://docs.oracle.com/en-us/iaas/Content/generative-ai/imported-nvidia-models.htm + - Name: **NVIDIA-Nemotron-3-Nano-30B-A3B-FP8** + - Description (optional): **Imported directly from Hugging Face** + - Vendor (optional): **NVIDIA** + - Version (optional): **1.0** +5. In Import configuration: + - Data source type: **HuggingFace** + - Model ID: **nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8** + - HuggingFace Token: paste the copied token ##hugging-face-token## + ![dac](images/dac0.png) +6. Click **Next**, then **Save**, and wait until the imported model is active. For this model, it takes about three minutes. +7. In the left-hand menu, go to **Dedicated AI clusters**. +8. Click **Create dedicated AI cluster**. + - Name: **dac-vibe*** + - Base model: **nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8** + - Unit shape: **H100 X4** (or **H100 X2** if you accept slower performance) + - Model replica: **1** + ![dac](images/dac1.png) +9. Wait until the DAC is active. +10. Go to **Endpoints**. + ![dac](images/dac2.png) +11. Click **Create endpoint**. + - Name: **dac-endpoint*** + - Model: **NVIDIA-Nemotron-3-Nano-30B-A3B-FP8** + - Click **Create**. + ![dac](images/dac3.png) + - Open the endpoint, copy the endpoint OCID, and add it to your notes as ##GENAI_DAC_ENDPOINT_OCID##. +12. When the endpoint is active (which can take 15 minutes or more, depending on the model size), try it using **View in Playground** in the top-left corner. Try “tell me a joke” or “who are you?” + ![dac](images/dac4.png) + + +## Known Issues + +- None + +## Acknowledgements + +- **Author** + - Marc Gueury, AI Agents Black Belt + - Ilayda Temir, Generative AI Black Belt diff --git a/oci-langchain-dac-lab/2-test/files/oci-langchain-dac.zip b/oci-langchain-dac-lab/2-test/files/oci-langchain-dac.zip new file mode 100644 index 000000000..d22c4caf8 Binary files /dev/null and b/oci-langchain-dac-lab/2-test/files/oci-langchain-dac.zip differ diff --git a/oci-langchain-dac-lab/2-test/images/editor1.png b/oci-langchain-dac-lab/2-test/images/editor1.png new file mode 100644 index 000000000..0448dd516 Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/editor1.png differ diff --git a/oci-langchain-dac-lab/2-test/images/editor2.png b/oci-langchain-dac-lab/2-test/images/editor2.png new file mode 100644 index 000000000..a802d8ed4 Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/editor2.png differ diff --git a/oci-langchain-dac-lab/2-test/images/editor3.png b/oci-langchain-dac-lab/2-test/images/editor3.png new file mode 100644 index 000000000..3972a3d96 Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/editor3.png differ diff --git a/oci-langchain-dac-lab/2-test/images/env_dac.png b/oci-langchain-dac-lab/2-test/images/env_dac.png new file mode 100644 index 000000000..d4e6b015b Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/env_dac.png differ diff --git a/oci-langchain-dac-lab/2-test/images/env_no_dac.png b/oci-langchain-dac-lab/2-test/images/env_no_dac.png new file mode 100644 index 000000000..4db985c35 Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/env_no_dac.png differ diff --git a/oci-langchain-dac-lab/2-test/images/ex1.png b/oci-langchain-dac-lab/2-test/images/ex1.png new file mode 100644 index 000000000..c945cd931 Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/ex1.png differ diff --git a/oci-langchain-dac-lab/2-test/images/ex1_graph.png b/oci-langchain-dac-lab/2-test/images/ex1_graph.png new file mode 100644 index 000000000..62dc90348 Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/ex1_graph.png differ diff --git a/oci-langchain-dac-lab/2-test/images/ex2.png b/oci-langchain-dac-lab/2-test/images/ex2.png new file mode 100644 index 000000000..30ce8f143 Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/ex2.png differ diff --git a/oci-langchain-dac-lab/2-test/images/ex3.png b/oci-langchain-dac-lab/2-test/images/ex3.png new file mode 100644 index 000000000..15c060b7a Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/ex3.png differ diff --git a/oci-langchain-dac-lab/2-test/images/ex4.png b/oci-langchain-dac-lab/2-test/images/ex4.png new file mode 100644 index 000000000..e0b76e50b Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/ex4.png differ diff --git a/oci-langchain-dac-lab/2-test/images/ex5.png b/oci-langchain-dac-lab/2-test/images/ex5.png new file mode 100644 index 000000000..c7ba49d2d Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/ex5.png differ diff --git a/oci-langchain-dac-lab/2-test/images/ex5_2.png b/oci-langchain-dac-lab/2-test/images/ex5_2.png new file mode 100644 index 000000000..b22015cab Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/ex5_2.png differ diff --git a/oci-langchain-dac-lab/2-test/images/lg-architecture.png b/oci-langchain-dac-lab/2-test/images/lg-architecture.png new file mode 100644 index 000000000..c256b17d5 Binary files /dev/null and b/oci-langchain-dac-lab/2-test/images/lg-architecture.png differ diff --git a/oci-langchain-dac-lab/2-test/test.md b/oci-langchain-dac-lab/2-test/test.md new file mode 100644 index 000000000..833c855e4 --- /dev/null +++ b/oci-langchain-dac-lab/2-test/test.md @@ -0,0 +1,337 @@ +# Explore and Test + +## Introduction + +In this lab, we will download, explore and test the LangGraph and LangChain examples. + +Each example uses OCI Generative AI and runs locally in Cloud Shell. + +We will cover the following agent architectures: + +![Agent Architecture](images/lg-architecture.png =50%x*) + +Estimated time: 20 min + +### Objectives + +- Explore a LangGraph agent with tools. +- Test conversation history, reusable tools, agent reflection, and a supervisor pattern. + +We will test the following architecture: + +1. Agent built using a graph +2. Agent (React) +3. Agent with tracing +4. Reflection (2 agents working as a team) +5. Supervisor: a main agent that calls other agents and loops until it finds a satisfactory answer + +### Download the examples + +Let's install the examples in Cloud Editor. + +1. Go to your OCI Home page. +2. Start *Cloud Editor*. +3. Double-check that the network is *Public*. If not, change it to *Public*. +4. In the *Terminal* menu, click *New Terminal*. +5. In the terminal, clone the example directory. Review `install.sh`, then run it to install a new Python version and the libraries used by the examples. + + ``` + + cd $HOME + wget https://livelabs.oracle.com/cdn/oci/oci-langchain-dac-lab/2-test/files/oci-langchain-dac.zip + unzip oci-langchain-dac.zip + cd oci-langchain-dac + cp .env.example .env + cat install.sh + ./install.sh + source .venv/bin/activate + + ``` + + ![Cloud Editor](images/editor1.png) + + If you have issue with the above link, you can also clone from the original git repo. + ```` + + cd $HOME + git clone https://github.com/mgueury/oci-langchain-dac.git + ... + + ```` + +6. After installation, the command *"source .venv/bin/activate"* activates the Python virtual environment. It must remain active to run any of the examples. + + If you close and restart Cloud Editor, reactivate the virtual environment by running: + + ```` + + cd $HOME/oci-langchain-dac + source .venv/bin/activate + + ```` + +7. Open the directory *oci-langchain-dac* + + - In the menu, click *File/Open* + - Choose the directory *oci-langchain-dac* + - Click *Open* + - You will see the directory with the example on the left. + + ![Cloud Editor](images/editor2.png) + +8. Configure based on your notes taken in the first lab. + + - In the menu, click *File/Open* + - In the dialog box, check *Show hidden files* + - Choose the file *.env* + - Click *Open* + + ![Cloud Editor](images/editor3.png) + +9. Edit the file and enter the values from your notes. + + The configuration depends on whether you installed a DAC or your instructor gave you access to one. + + With DAC: + ``` + + GENAI_MODEL=##GENAI_DAC_ENDPOINT_OCID## + ex: GENAI_MODEL=ocid1.generativeaiendpoint.oc1.xxxxxxxxxx + REGION=##REGION## + ex: REGION=us-chicago-1 + COMPARTMENT_OCID=##COMPARTMENT_OCID## + ex: COMPARTMENT_OCID=ocid1.compartment.oc1.xxxxxxxxxx + + ``` + + ![.env DAC](images/env_dac.png) + + Without a DAC (for example, if you have access to the Chicago region): + ``` + + GENAI_MODEL=xai.grok-4.20-0309-reasoning + REGION=us-chicago-1 + COMPARTMENT_OCID=##COMPARTMENT_OCID## + ex: COMPARTMENT_OCID=ocid1.compartment.oc1.xxxxxxxxxx + + ``` + + ![.env no DAC](images/env_no_dac.png) + +## Task 1: LangGraph Agent + +Let's look at our first agent. It uses a LangGraph workflow, an OCI Generative AI model, and a weather tool to recommend clothing. + +1. Open `ex1_langgraph.py` in Cloud Shell Editor or VS Code. +2. Check the `get_current_weather` tool. It calls OpenWeather and returns structured weather data. +3. Check how the graph is built. The flow is **model → tool → model**: + + ```python + graph.add_node("assistant", call_model) + graph.add_node("tools", ToolNode(tool_list)) + graph.add_edge(START, "assistant") + graph.add_conditional_edges("assistant", tools_condition, {"tools": "tools", END: END}) + graph.add_edge("tools", "assistant") + ``` + + The conditional edge sends a request to the tool only when the model has made a tool call. Otherwise, the graph ends. This is the way that agents work. They are based on execution graphs. With LangGraph, it is defined explicitly. + ![Graph](images/ex1_graph.png) + +4. Run the example: + + ``` + + cd $HOME/oci-langchain-dac + source .venv/bin/activate + python3 ex1_langgraph.py + + ``` + + ![ex1](images/ex1.png) + +5. Run the following questions: + + - *What should I wear in Las Vegas today?* + - *Should I take an umbrella in London, GB?* + +6. Notice that the agent calls the weather tool before giving weather-dependent advice. Type `quit` or CTRL+C to leave the program. + +## Task 2: Agent + +In the previous sample, the graph is written explicitly. This example uses LangChain's prebuilt *Agent* loop and keeps the chat history in the local `conversation` list. Basically, this is the same than previous example. Here with the new Agent syntax. + +1. Open `ex2_agent.py`. +2. Check the agent definition. `create_agent` creates the ReAct loop and receives the OCI model, weather tool, and system prompt. + + ```python + agent = create_agent(model, [get_current_weather], system_prompt=(...)) + ``` + +3. Check the last lines of the program. After every turn, the returned messages replace `conversation`; the next invocation includes those messages. + + ```python + conversation = agent.invoke( + {"messages": [*conversation, HumanMessage(question)]} + )["messages"] + ``` + + The history is kept in memory only. Restarting the program starts a new conversation. + +4. In the terminal, run the following command: + + ``` + + python3 ex2_agent.py + + ``` + + ![ex2](images/ex2.png) + +5. Run the following questions in the same conversation: + + - *I am travelling to Brussels, BE today. What should I wear?* + - *What about footwear?* + + Notice that the second answer can use the city and weather context from the previous turn. + +6. Type `quit` to leave the program. + +## Task 3: Agent with tracing + +In this version of the lab, +- tracing is enabled, +- and reusable tools are separated from the agent. +This is the building block used later by the supervisor to route requests to specialist agents. The explicit human-confirmation step is exercised in Task 5. + +1. Open `ex3_agent_trace.py` and `tools.py`. +2. Notice that the agent imports `get_current_weather` from `tools.py` rather than defining the tool in the application file. + + ```python + from tools import get_current_weather + ``` + + This structure lets several agents use the same tool implementation while keeping the agent code small. + +3. Run the example: + + ``` + + python3 ex3_agent_trace.py + + ``` + ![ex3](images/ex3.png) + +4. Run the following questions: + + - *How should I dress for the weather in Sydney, AU?* + +5. Type `quit` to leave the program. + +## Task 4: Reflection + +Here we will use two agents that work together. + +- One agent produces a Markdown document from an English Wikipedia page. +- The other agent checks grammar and structure. The document is shown only when the reviewer approves it. + +1. Open `ex4_reflection.py`. +2. Check `writer_agent` and `reviewer_agent`. + - The writer must call `get_wikipedia_page` before writing. + - The reviewer returns a structured `DocumentReview` with `approved` and `feedback` fields. +3. Check the revision loop. The writer can revise a draft up to three times: + + ```python + for attempt in range(MAX_REVISIONS): + review = review_document(draft) + if review.approved: + ... + draft = write_document(...) + ``` + +4. Run the example: + + ``` + + python3 ex4_reflection.py + + ``` + + ![ex4](images/ex4.png) + +5. Enter one of the following Wikipedia page titles: + + - *Iron Man* + +6. Notice that the reviewer and writer speaks between themselves before to give the final document. Type `quit` to leave the program. + +## Task 5: Supervisor + +Here, we will use a group of agents working together with a supervisor to coordinate their work. + +The supervisor has two tasks: + +- Route HR policy questions to the HR FAQ specialist. +- Route holiday booking and balance requests to the booking specialist. + +The booking specialist introduces a human-in-the-loop step: it proposes exact dates first and writes the booking only after the user explicitly confirms it. + +1. Open `ex5_supervisor.py` and review the three agents: + - `hr_agent` uses `search_hr_faq`. + - `booking_agent` uses the holiday tools. + - `holiday_agent` is the supervisor. It uses `ask_hr_agent` and `ask_booking_agent` to route the request. +2. Check the booking-agent prompt. It permits `confirm_holiday_booking` only after an explicit confirmation. +3. Run the example: + + ``` + + python3 ex5_supervisor.py + + ``` + + ![ex5](images/ex5.png) + +4. Run the following questions in order: + + - *Book a holiday tomorrow.* + - *Confirm.* + - *Send a mail with my holiday balance to test@oracle.com* + +5. Notice that the supervisor calls subagents using natural-language requests. For example, it asks the booking subagent to book a holiday. Tools, by contrast, are called with parameters. During the process, the user is asked to confirm the booking. This is called **human-in-the-loop**. +6. Notice that, for complex questions, the agent calls the tools and subagents it needs before answering. For example, it can first collect data through subagents and then call its own tools. + + ![ex1](images/ex5_2.png) + +7. Type `quit` to leave the program. + +## END + +Congratulations! You have finished the lab!! +We hope you have learned something useful. + +## Known issues + +- When starting an example, you have this error: + ``` + + Traceback (most recent call last): + File "/home/marc_gueur/oci-langchain-dac/ex1_langgraph.py", line 5, in + import common + File "/home/marc_gueur/oci-langchain-dac/common.py", line 9, in + from langchain_core.messages import AIMessage, ToolMessage + ModuleNotFoundError: No module named 'langchain_core' + + ``` + Solution: The python virtual env is not activated. Run + ``` + + source .venv/bin/activate + + ``` +- `OPENWEATHER_API_KEY` must be valid for Tasks 1–3. If it is missing, the weather tool reports that configuration issue instead of returning weather data. +- The examples need outbound network access to OCI Generative AI. Tasks 1–3 also call OpenWeather; Task 4 calls English Wikipedia. +- `holiday.json` is created by Task 5 after a confirmed booking. Delete that file manually before rerunning the task if you need a completely empty booking history. + +## Acknowledgements + +- **Author** + - Marc Gueury, Oracle Generative AI Platform diff --git a/oci-langchain-dac-lab/workshops/freetier/index.html b/oci-langchain-dac-lab/workshops/freetier/index.html new file mode 100644 index 000000000..471847eb9 --- /dev/null +++ b/oci-langchain-dac-lab/workshops/freetier/index.html @@ -0,0 +1,63 @@ + + + + + + + + + Oracle LiveLabs + + + + + + + + + + + + + +
+
+
+
+
+
+
+
+ + + + + diff --git a/oci-langchain-dac-lab/workshops/freetier/manifest.json b/oci-langchain-dac-lab/workshops/freetier/manifest.json new file mode 100644 index 000000000..473e5958d --- /dev/null +++ b/oci-langchain-dac-lab/workshops/freetier/manifest.json @@ -0,0 +1,26 @@ +{ + "workshoptitle": "Deploy LangChain Agents with OCI Enterprise AI", + "help": "livelabs-help-oci_us@oracle.com", + "tutorials": [ + { + "title": "Introduction", + "filename": "./../../0-intro/intro.md" + }, + { + "title": "Get Started", + "filename": "https://livelabs.oracle.com/cdn/common/labs/cloud-login/event-register-free-tier-account.md" + }, + { + "title": "Lab 1: Install the components", + "filename": "./../../1-install/install.md" + }, + { + "title": "Lab 2: Explore and Test", + "filename": "./../../2-test/test.md" + }, + { + "title": "Need Help", + "filename": "https://livelabs.oracle.com/cdn/common/labs/need-help/need-help-freetier.md" + } + ] +} diff --git a/oci-starter-lab/container_instance/container_instance.md b/oci-starter-lab/container_instance/container_instance.md index 2d3b6d507..e36aec873 100644 --- a/oci-starter-lab/container_instance/container_instance.md +++ b/oci-starter-lab/container_instance/container_instance.md @@ -11,7 +11,7 @@ Estimated time: 10 min In this sample, using terraform, we will create: - a Container Instance running 2 docker containers -- 1 container with a Java program +- 1 container with a .NET program - 1 container with HTML pages on NGINX - and an Autonomous Database. diff --git a/oci-starter-lab/customize/customize.md b/oci-starter-lab/customize/customize.md index fe089f93c..bf9c218d3 100644 --- a/oci-starter-lab/customize/customize.md +++ b/oci-starter-lab/customize/customize.md @@ -29,10 +29,10 @@ Let's say that we deploy a Java / SpringBoot on a Compute with an Database. 1. Create resources (compute/database/....) with "Terraform" (src/terraform) 2. Create tables in the database (src/db) 3. Compile the "Backend Application (app)" (src/app) - - script: src/app/build_app.sh + - script: src/app/build.sh - output directory: target/compute/app 4. Compile the "User Interface (ui)" (src/ui) - - script: src/ui/build_ui.sh + - script: src/ui/build.sh - output directory: target/compute/ui 5. Deploy the "app" and "ui" to the compute: - the target/app and target/ui are copied to the compute @@ -102,12 +102,12 @@ In the next task, we will go inside each directory to see what it contains. ```` ```` - app.yaml build_app.sh Dockerfile openapi_spec.yaml pom.xml src start.sh target + app.yaml build.sh Dockerfile openapi_spec.yaml pom.xml src start.sh target ```` 2. There are 2 types of files: 1. The files to build the application - - build_app.sh : script to build the application (output target/compute/app) + - build.sh : script to build the application (output target/compute/app) - Dockerfile : file to build docker image (Kubernetes and Container Instance deployment) - app.yaml : kubernetes deployment file for the application - openapi_spec.yaml : OpenAPI specification of the Application (documentation only) @@ -131,12 +131,12 @@ In the next task, we will go inside each directory to see what it contains. ```` ```` - build_ui.sh Dockerfile ui ui.yaml + build.sh Dockerfile ui ui.yaml ```` 2. We see 2 types of files: 1. The files to build the User Interface - - build_ui.sh : script to build the user interface (output target/compute/ui) + - build.sh : script to build the user interface (output target/compute/ui) - Dockerfile : file to build docker image (Kubernetes and Container Instance deployment) - ui.yaml : kubernetes deployment file for the user interface 2. The application source files @@ -149,4 +149,4 @@ In the next task, we will go inside each directory to see what it contains. * Author - Marc Gueury * Contributors - Ewan Slater -* Last Updated - Jan, 20th 2025 \ No newline at end of file +* Last Updated - Sept, 6th 2026 \ No newline at end of file diff --git a/oci-starter-lab/function/function.md b/oci-starter-lab/function/function.md index de6b283dc..368dbe59d 100644 --- a/oci-starter-lab/function/function.md +++ b/oci-starter-lab/function/function.md @@ -105,7 +105,7 @@ Before to run the build. Notice that the build will create: - Rest Info API : https://xxxxxx.apigateway.eu-xxxx.oci.customer-oci.com/starter/info ``` -2. Notice, during a cold start, the first function call with take about 40 secs to run. If you want instant response, you need to configure the [Provisioned Concurrency](https://docs.oracle.com/en-us/iaas/Content/Functions/Tasks/functionsusingprovisionedconcurrency.htm]. +2. Notice, during a cold start, the first function call with take about 40 secs to run. If you want instant response, you need to configure the [Provisioned Concurrency](https://docs.oracle.com/en-us/iaas/Content/Functions/Tasks/functionsusingprovisionedconcurrency.htm). 3. Click on the URL or go to the link to check that it works: - All running in Serverless Mode - You have HTML pages stored in Object Storage doing REST calls diff --git a/oci-starter-lab/intro/intro.md b/oci-starter-lab/intro/intro.md index da0c212c7..3cdf1509f 100644 --- a/oci-starter-lab/intro/intro.md +++ b/oci-starter-lab/intro/intro.md @@ -150,6 +150,6 @@ In short, * Author - Marc Gueury * Contributors - Ewan Slater -* Last Updated - Jan, 20th 2025 +* Last Updated - Sept, 6th 2026 diff --git a/oci-starter-lab/public_compute/images/starter-compute-result.png b/oci-starter-lab/public_compute/images/starter-compute-result.png index 5e7a46fa0..a5c7c0bc2 100644 Binary files a/oci-starter-lab/public_compute/images/starter-compute-result.png and b/oci-starter-lab/public_compute/images/starter-compute-result.png differ diff --git a/oci-vibe-dac-lab/0-intro/images/opencode-lab-hello-game.png b/oci-vibe-dac-lab/0-intro/images/opencode-lab-hello-game.png new file mode 100644 index 000000000..5b69c3318 Binary files /dev/null and b/oci-vibe-dac-lab/0-intro/images/opencode-lab-hello-game.png differ diff --git a/oci-vibe-dac-lab/0-intro/images/opencode-lab-install.png b/oci-vibe-dac-lab/0-intro/images/opencode-lab-install.png new file mode 100644 index 000000000..75ee66090 Binary files /dev/null and b/oci-vibe-dac-lab/0-intro/images/opencode-lab-install.png differ diff --git a/oci-vibe-dac-lab/0-intro/intro.md b/oci-vibe-dac-lab/0-intro/intro.md new file mode 100755 index 000000000..fd7661a9a --- /dev/null +++ b/oci-vibe-dac-lab/0-intro/intro.md @@ -0,0 +1,51 @@ + +# Introduction + +### Objectives + +This lab introduces a modern, AI development workflow referred to as *Vibe Coding*—a practical approach that blends developer intuition with powerful AI tools to accelerate software delivery, improve code quality, and streamline operations. + +Rather than focusing purely on theory, these labs are hands-on and iterative. You will progressively build programs using: +- a Large Language Model; +- an OpenAI-compatible API key; +- an on-demand model; +- or a Dedicated AI Cluster (DAC) to import open-weight models from Hugging Face. + - See https://docs.oracle.com/en-us/iaas/Content/generative-ai/imported-models.htm. + - For example, models include Alibaba Qwen, DeepSeek, Google Gemma, Meta Llama, Microsoft Phi, MiniMax, Mistral, Moonshot AI Kimi, NVIDIA Nemotron, OpenAI Whisper, OpenAI GptOss, and Z.ai GLM. +- a coding agent: OpenCode. + +Estimated Workshop Time: 60 minutes + +### What You Will Learn + +In these labs, you will get an introduction to how to: +- Set up and configure a Vibe Coding environment on OCI. +- Deploy a Dedicated AI Cluster. +- Generate and execute code using natural-language prompts (Hello World and Space Invaders). + +### Lab 1: Installation + +You will then configure OCI to use Generative AI. +- Create a compartment. +- Configure a policy. +- Create OpenAI-compatible API keys. +- Optionally, explore setting up a DAC (Dedicated AI Cluster) using imported models such as Nemotron, Qwen, and Gemma. + +![Install](images/opencode-lab-install.png) + +### Lab 2: Vibe Coding + +You will start by setting up your development environment, installing and integrating OpenCode, and generating your first “Hello World” application. + +![Hello World + Games](images/opencode-lab-hello-game.png) + +## About This Workshop + +You will have built several programs using Vibe Coding and deployed one in the cloud. + +**Please proceed to the [next lab](#next).** + +## Acknowledgements + +- **Author** + - Marc Gueury, AI Agents Black Belt diff --git a/oci-vibe-dac-lab/1-install/images/api_key1.png b/oci-vibe-dac-lab/1-install/images/api_key1.png new file mode 100755 index 000000000..72f87d282 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/api_key1.png differ diff --git a/oci-vibe-dac-lab/1-install/images/api_key2.png b/oci-vibe-dac-lab/1-install/images/api_key2.png new file mode 100755 index 000000000..f5df6af37 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/api_key2.png differ diff --git a/oci-vibe-dac-lab/1-install/images/api_key3.png b/oci-vibe-dac-lab/1-install/images/api_key3.png new file mode 100755 index 000000000..4a85226ec Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/api_key3.png differ diff --git a/oci-vibe-dac-lab/1-install/images/chicago-region.png b/oci-vibe-dac-lab/1-install/images/chicago-region.png new file mode 100755 index 000000000..0282242b8 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/chicago-region.png differ diff --git a/oci-vibe-dac-lab/1-install/images/cloud-shell-public-network.png b/oci-vibe-dac-lab/1-install/images/cloud-shell-public-network.png new file mode 100755 index 000000000..b0ce5b966 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/cloud-shell-public-network.png differ diff --git a/oci-vibe-dac-lab/1-install/images/compartment1.png b/oci-vibe-dac-lab/1-install/images/compartment1.png new file mode 100755 index 000000000..826045e4f Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/compartment1.png differ diff --git a/oci-vibe-dac-lab/1-install/images/compartment2.png b/oci-vibe-dac-lab/1-install/images/compartment2.png new file mode 100755 index 000000000..fc58d9f36 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/compartment2.png differ diff --git a/oci-vibe-dac-lab/1-install/images/dac0.png b/oci-vibe-dac-lab/1-install/images/dac0.png new file mode 100755 index 000000000..22624c678 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/dac0.png differ diff --git a/oci-vibe-dac-lab/1-install/images/dac1.png b/oci-vibe-dac-lab/1-install/images/dac1.png new file mode 100755 index 000000000..2943c1129 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/dac1.png differ diff --git a/oci-vibe-dac-lab/1-install/images/dac2.png b/oci-vibe-dac-lab/1-install/images/dac2.png new file mode 100755 index 000000000..19342243a Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/dac2.png differ diff --git a/oci-vibe-dac-lab/1-install/images/dac3.png b/oci-vibe-dac-lab/1-install/images/dac3.png new file mode 100755 index 000000000..e2e84cd43 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/dac3.png differ diff --git a/oci-vibe-dac-lab/1-install/images/dac4.png b/oci-vibe-dac-lab/1-install/images/dac4.png new file mode 100755 index 000000000..d0aaeb7db Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/dac4.png differ diff --git a/oci-vibe-dac-lab/1-install/images/hugging-face1.png b/oci-vibe-dac-lab/1-install/images/hugging-face1.png new file mode 100755 index 000000000..8c68c7586 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/hugging-face1.png differ diff --git a/oci-vibe-dac-lab/1-install/images/hugging-face2.png b/oci-vibe-dac-lab/1-install/images/hugging-face2.png new file mode 100755 index 000000000..c2269b3f0 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/hugging-face2.png differ diff --git a/oci-vibe-dac-lab/1-install/images/imported-model1.png b/oci-vibe-dac-lab/1-install/images/imported-model1.png new file mode 100755 index 000000000..2ec3dd8b7 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/imported-model1.png differ diff --git a/oci-vibe-dac-lab/1-install/images/policy-create.png b/oci-vibe-dac-lab/1-install/images/policy-create.png new file mode 100755 index 000000000..54c2aa252 Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/policy-create.png differ diff --git a/oci-vibe-dac-lab/1-install/images/policy-menu.png b/oci-vibe-dac-lab/1-install/images/policy-menu.png new file mode 100755 index 000000000..f1cc6720c Binary files /dev/null and b/oci-vibe-dac-lab/1-install/images/policy-menu.png differ diff --git a/oci-vibe-dac-lab/1-install/install.md b/oci-vibe-dac-lab/1-install/install.md new file mode 100755 index 000000000..9c2fbfa5a --- /dev/null +++ b/oci-vibe-dac-lab/1-install/install.md @@ -0,0 +1,209 @@ +# Setup + +## Introduction +In this lab, you will prepare OCI to use Generative AI / Large Language models. + +Optionally, you will import an open-weight model in a Dedicated AI Cluster (DAC). + +DAC-hosted models run on dedicated infrastructure in your tenancy. Use a DAC-hosted model when you need production-grade control over model hosting and inference. DACs provide several advantages: Flexibility, Isolation, Predictable latency, Fine-tuning support, Cost efficiency at scale, Deployment near data, Simplified management + +Estimated time: 30 min + +### Objectives + +- Configure OCI Generative AI access, Visual Studio Code, and Cline, then generate a Hello World app. + +### Prerequisites + +- An OCI account with sufficient credits for completing the lab. (Some of the services used in this lab are not part of the *Always Free* program.) +- Check that your tenancy has access to a Generative AI region, such as **Frankfurt, London, Chicago, Abu Dhabi, Riyadh, or Osaka**. See the full list here: https://docs.oracle.com/en-us/iaas/Content/generative-ai/regions.htm + - **For Paid Tenancy** + - Click the region selector at the top of the screen. + - Check that your tenancy is subscribed to one of the above regions. + - If not, click **Manage Regions** to add it to your regions list. You need tenancy administrator rights for this. + - For example, click on the US Midwest (Chicago). + - Click **Subscribe**. + + ![Chicago Region](images/chicago-region.png) + + - **For Free Trial**, the home region should be one where Generative AI On Demand is available. +- The lab is using Cloud Shell with Public Network. + + The lab assumes that you have access to OCI Cloud Shell with Public Network access. + To check whether you have it, start Cloud Shell. You should see **Network: Public** at the top. If not, try changing to **Public Network**. If it works, there is nothing else to do. + ![Cloud Shell Public Network](images/cloud-shell-public-network.png) + + OCI administrators have this permission automatically, or your administrator may have already added the required policy. + - **Solution:** + + If not, ask your administrator to follow this document: + + https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cloudshellintro_topic-Cloud_Shell_Networking.htm#cloudshellintro_topic-Cloud_Shell_Public_Network + + He/She just needs to add a policy to your tenancy: + + ``` + + allow group to use cloud-shell-public-network in tenancy + + ``` + +## Task 1: Prepare to save configuration settings + +1. Open a text editor and copy and paste this text into a file on your local computer. These are the variables used during the lab. + + ``` + + List of ##VARIABLES## + ===================== + REGION=(SAMPLE) eu-frankfurt-1 + COMPARTMENT_OCID=(SAMPLE) ocid1.compartment.oc1.xxxxxxx + api-key1=(SAMPLE) sk-xxxxxxxxxxxxxx + api-key2=(SAMPLE) sk-xxxxxxxxxxxxxx + OBJECT_STORAGE_NAME=(SAMPLE) bucket-123456 + + Optional + ======== + hugging-face-token=(SAMPLE) hf_xxxxxxxxxxxxxxxxxxxx + BASE_URL=(sample) https://inference.generativeai.eu-frankfurt-1.oci.oraclecloud.com/openai/v1/chat/completions + GENAI_DAC_ENDPOINT_OCID=(SAMPLE) ocid1.generativeaiendpoint.oc1.xxxxxxxxxx + + + + ----------------------------------------------------------------------- + + ``` + +## Task 2: Create a Compartment + +The compartment will be used to contain all the components of the lab. + +You can: +- Use an existing compartment to run the lab. +- Create a new one (recommended). + +1. Log in to your OCI account/tenancy. +2. Double-check that you are in a region with GenAI available. +3. Go to the 3-bar/hamburger menu of the console, then Identity & Security > Compartments. + ![Menu Compartment](images/compartment1.png) +4. Click ***Create Compartment***. + - Give it a name, for example, ***VIBE-AI***. + - Click ***Create Compartment*** again. + ![Create Compartment](images/compartment2.png) +5. When the compartment is created, copy the compartment OCID, ##COMPARTMENT_OCID##, and add it to your notes. + +## Task 3: Create an API Key + +First, create an OpenAI-compatible API key. +1. Log in to the OCI Console. Record the region name in your notes as ##REGION##. You should be in a region with Generative AI. See the full list here: https://docs.oracle.com/en-us/iaas/Content/generative-ai/regions.htm +2. Click the hamburger menu / AI & Analytics / Generative AI. + + ![API_KEY](images/api_key1.png) + +3. Go to **API Keys** on the right side. +4. Click **Create API key**. + + ![API_KEY](images/api_key2.png) + +5. Fill in the following: + - Name: **api-key** + - Key one name: **api-key1** + - Key one expiration date: **7/20/2030** (a date far in the future) + - Key two name: **api-key2** + - Key two expiration date: **7/20/2030** (a date far in the future) + - Click *Create*. + + ![API_KEY](images/api_key3.png) + +6. Copy the values of the two keys in your notes (##api-key1##, ##api-key2##). + - api-key1=sk-xxxxxxxxx + - api-key2=sk-xxxxxxxxx + - Click **Close**. +While you can choose any model from any provider to continue this lab, this lab covers several models available in OCI. + +## Task 4: Create a Policy + +- Go to the OCI Console menu and choose *Identity & Security* / *Policies*. + ![Policy Menu](images/policy-menu.png) +- Click *Create Policy*. +- Name: *policy-vibe* +- Description: *policy-vibe* +- Click *Show Manual editor*. +- Copy the following, replacing ##COMPARTMENT\_OCID## with your value: + ``` + allow any-user to manage generative-ai-family in compartment id ##COMPARTMENT_OCID## where request.principal.type = 'generativeaiapikey' + ``` +- Click *Create*. + ![Policy Create](images/policy-create.png) + +## Task 5: Install a Dedicated AI Cluster (DAC) - Optional + +⚠️ This optional task starts a GPU for at least one hour, so it may cost several euros per hour. Do not forget to stop the DAC after testing. + +We will follow this process: https://docs.oracle.com/en-us/iaas/Content/generative-ai/imported-models.htm + +DAC-hosted models run on dedicated infrastructure in your tenancy. Use a DAC-hosted model when you need production-grade control over model hosting and inference. DACs provide several advantages: + +- **Flexibility:** Import supported Hugging Face-format models from Hugging Face or Object Storage, test imported models with shorter commitments, choose fine-tuned or quantized versions, and right-size based on visible hardware specifications. +- **Isolation:** Run workloads on dedicated GPU resources inside your tenancy, which helps protect sensitive data, avoids shared-resource contention, and supports regulated workloads. +- **Predictable latency:** Dedicated infrastructure can provide more stable time-to-first-token and inference response times than shared model endpoints, especially for scaling production applications. +- **Fine-tuning support:** Host fine-tuned models alongside base models, run multiple fine-tuned models on a single cluster, and control model lifecycle and upgrade cadence. +- **Cost efficiency at scale:** For inference-heavy workloads, DACs can reduce effective price per token by keeping dedicated resources highly utilized and hosting multiple models on one cluster. +- **Deployment near data:** Deploy in supported OCI regions, including regulated regions where available, to support data residency, lower latency, and simpler security reviews. +- **Simplified management:** OCI manages the infrastructure while you manage model deployment, scaling, fine-tuning, and application integration. + +Documentation: https://docs.oracle.com/en-us/iaas/Content/generative-ai/import-model-from-hugging-face.htm#top + +1. Create a Hugging Face token. + - Open https://huggingface.co/ in your browser. + - Log in or sign up. + - Go to Hugging Face / Settings / Access Tokens. + - Click **Create new token**. + ![Hugging face](images/hugging-face1.png) + - Use either a read token (easier) or, preferably for production, a fine-grained token scoped to the model repository. + - Copy the token into your notes as ##hugging-face-token##. + ![Hugging face](images/hugging-face2.png) +2. In OCI Console, go to Analytics & AI / Generative AI / Imported models. +3. Click **Create Imported model**. + ![imported model](images/imported-model1.png) +4. Enter model metadata: + - New models are added so quickly that the list may differ when you read this lab. Choose the model that best suits your needs. Here, we use this model from NVIDIA: https://docs.oracle.com/en-us/iaas/Content/generative-ai/imported-nvidia-models.htm + - Name: **NVIDIA-Nemotron-3-Nano-30B-A3B-FP8** + - Description (optional): **Imported directly from Hugging Face** + - Vendor (optional): **NVIDIA** + - Version (optional): **1.0** +5. In Import configuration: + - Data source type: **HuggingFace** + - Model ID: **nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8** + - HuggingFace Token: paste the copied token ##hugging-face-token## + ![dac](images/dac0.png) +6. Click **Next**, then **Save**, and wait until the imported model is active. For this model, it takes about three minutes. +7. In the left-hand menu, go to **Dedicated AI clusters**. +8. Click **Create dedicated AI cluster**. + - Name: **dac-vibe*** + - Base model: **nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8** + - Unit shape: **H100 X4** (or **H100 X2** if you accept slower performance) + - Model replica: **1** + ![dac](images/dac1.png) +9. Wait until the DAC is active. +10. Go to **Endpoints**. + ![dac](images/dac2.png) +11. Click **Create endpoint**. + - Name: **dac-endpoint*** + - Model: **NVIDIA-Nemotron-3-Nano-30B-A3B-FP8** + - Click **Create**. + ![dac](images/dac3.png) + - Open the endpoint, copy the endpoint OCID, and add it to your notes as ##GENAI_DAC_ENDPOINT_OCID##. +12. When the endpoint is active (which can take 15 minutes or more, depending on the model size), try it using **View in Playground** in the top-left corner. Try “tell me a joke” or “who are you?” + ![dac](images/dac4.png) + + +## Known Issue + +- None + +## Acknowledgements + +- **Author** + - Marc Gueury, AI Agents Black Belt + - Ilayda Temir, Generative AI Black Belt diff --git a/oci-vibe-dac-lab/2-hello-game/files/oci-vibe-dac.zip b/oci-vibe-dac-lab/2-hello-game/files/oci-vibe-dac.zip new file mode 100644 index 000000000..e569c0393 Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/files/oci-vibe-dac.zip differ diff --git a/oci-vibe-dac-lab/2-hello-game/hello-game.md b/oci-vibe-dac-lab/2-hello-game/hello-game.md new file mode 100755 index 000000000..161a456f1 --- /dev/null +++ b/oci-vibe-dac-lab/2-hello-game/hello-game.md @@ -0,0 +1,242 @@ +# Hello World, Game and Mobile App + +## Introduction +In this lab, you will install OpenCode for Vibe Coding and generate: +- a small Hello World application, +- a Space Invaders game, +- a Mobile Application to order food in a restaurant. + +Estimated time: 30 min + +### Objectives + +- Install OpenCode in Cloud Shell. +- Vibe-code two applications. + +### Prerequisites + +Complete the previous lab. + +## Task 1: Install OpenCode in Cloud Shell + +To avoid installing OpenCode on your laptop, although you can also use OpenCode or OpenCode Desktop on it, we will use OCI Cloud Shell. + +For more information: https://opencode.ai/ + +1. Start Cloud Shell. + +2. Install OpenCode. + + ```` + + cd $HOME + wget https://livelabs.oracle.com/cdn/oci/oci-vibe-dac-lab/2-hello-game/files/oci-vibe-dac.zip + unzip oci-vibe-dac.zip + cd oci-vibe-dac + cat install_opencode.sh + ./install_opencode.sh + + ```` + + If you have issue with the above link, you can also clone from the original git repo. + ```` + + cd $HOME + git clone https://github.com/mgueury/oci-vibe-dac.git + ... + + ```` + + ![Install](images/opencode_install1.png) + + You will be asked some questions. The answers depend on whether you use a Dedicated AI Cluster. + - Without a DAC: + - If you have access to the Chicago region, use the proposed default value. + - Or look up the model and region here: https://docs.oracle.com/en-us/iaas/Content/generative-ai/model-endpoint-regions.htm. Find the base URL here: https://docs.oracle.com/en-us/iaas/api/#/en/generative-ai-inference/20231130/ + - Here is an example: + - Model ID: ex: *xai.grok-4.20-0309-reasoning* + - OCI Generative AI base URL: *https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1* + - Model name: *Grok* + - API Key: *sk-xxx* (see your notes in previous lab) + - With Dedicated AI Cluster (DAC): + - Model ID: ex: *ocid1.generativeaiendpoint.oc1.xxxxxx.amaaaaaaxxxx* + - API Key: *sk-xxx* (see your notes in previous lab) + +3. Create an Object Storage bucket. + + Run the script: + ```` + + cd $HOME/oci-vibe-dac + ./bucket_create.sh + -> Enter the Compartment OCID. See your notes in previous lab. + + ```` + ![Install](images/opencode_install2.png) + +## Task 2: Hello World + +1. Start OpenCode in the hello directory: + + ```` + + cd $HOME/oci-vibe-dac/hello + opencode + + ```` + +2. Type: **Who are you?** + + Notice that you receive the name of the coding agent rather than the AI model. + +3. Type: **What AI model do you use?** + + Now, you should get the AI model name. + + ![OpenCode](images/opencode1.png) + +4. Type: *Create a file with hello world in Python.* + +5. Type: *Execute it. Show the output.* + + ![OpenCode](images/opencode_hello.png) + +6. Optionally, ask the same in Java, Node.js, Go, or another language. + +7. Exit (press CTRL+C). + +## Task 3: Space Invaders + +1. Start OpenCode in the space-invaders directory. + + ```` + + cd $HOME/oci-vibe-dac/space-invaders + opencode + + ```` + +2. In the OpenCode prompt, type: *Write a Space Invaders game in HTML, JavaScript, and CSS.* + + ![Space Invaders](images/opencode_game1.png) + +3. Type: *Deploy it.* + + This uses a skill explained later in Task 5. + + ![Space Invaders](images/opencode_game2.png) + + You will receive a URL, for example: https://objectstorage.eu-frankfurt-1.oraclecloud.com/n/xxxx/b/space-invaders-xxxxx/o/index.html + + ![Space Invaders](images/space-invaders_grok420.png) + +## Task 4: Space Invaders: plan + build + +1. Return to OpenCode. +2. In the OpenCode prompt, press Tab. The agent will switch to Plan mode. + + ![OpenCode](images/opencode_plan1.png) + +3. Type: *Add a bonus flying saucer at the top of the screen. The speed is too slow.* + + ![OpenCode](images/opencode_plan2.png) + +4. OpenCode will ask some questions. Answer them, and then OpenCode will generate a plan. + + ![OpenCode](images/opencode_plan3.png) + +5. When ready, press Tab again to switch to Build mode. Then type: *Build it.* + + ![OpenCode](images/opencode_plan4.png) + +6. Check whether the flying saucer is there. + + ![Space Invaders](images/opencode_plan5.png) + +7. Exit (press CTRL+C). + +## Task 5: Mobile : plan + build + +1. Start OpenCode in the space-invaders directory. + + ```` + + cd $HOME/oci-vibe-dac/mobile + opencode + + ```` + +2. In the OpenCode prompt, press Tab. The agent will switch to Plan mode. + + ![OpenCode](images/opencode_plan1.png) + +3. Type: *Write an HTML mobile application to order food in a restaurant.* + +4. OpenCode will ask some questions. Answer them, and then OpenCode will generate a plan. + +5. When ready, press Tab again to switch to Build mode. Then type: *Build it.* + +6. Ask to deploy it: *Deploy*. Click on the HTML link. + + ![Restaurant](images/opencode_resto_qwen36_1.png) + ![Restaurant](images/opencode_resto_qwen36_2.png) + ![Restaurant](images/opencode_resto_qwen36_3.png) + +## Task 6: Skills + +During the two previous tasks, you used the deploy skill several times. It is a kind of prompt that defines a workflow or process. Let’s look at it. + +``` + +cd $HOME/oci-vibe-dac/space-invaders/.agents/skills/deploy/ +cat SKILL.md + +``` + +``` + +--- +name: deploy +description: Deploy the files in the current project directory to its existing OCI Object Storage bucket. Use when asked to upload, publish, or deploy the project from the current working directory after the bucket has been created. +--- + +# Deploy the Current Project + +1. Treat the current working directory as the project to upload; do not change directories before running: + +'''bash +project_directory=$(pwd -P) +repository_root=$(git rev-parse --show-toplevel) +''' + +2. Verify that `$repository_root/.bucket-name` exists and is nonempty. If it is missing, stop and tell the user to run `bucket_create.sh` first; do not create a bucket. +3. Upload the recorded project directory with the repository uploader: + +'''bash +"$repository_root/bucket_upload.sh" "$project_directory" +''' + +4. Show the end user the public HTML URL(s) given at the end of the script. + +``` + +When we asked for deployments during the chat with the coding agent, it used the SKILL.md file as the process for completing the request. + +For more information: https://agentskills.io/home + +" At its core, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, reference materials, templates, and other resources. " + +## Task 7: More models + +Try other models and repeat the exercises. New models are available regularly, and they are improving rapidly in performance and quality. + +## END + +Congratulations! You have finished the lab!! +We hope you have learned something useful. + +## Acknowledgements + +- **Author** + - Marc Gueury, AI Agents Black Belt + - Ilayda Temir, Generative AI Black Belt diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode1.png b/oci-vibe-dac-lab/2-hello-game/images/opencode1.png new file mode 100644 index 000000000..0c29b9b46 Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode1.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_game1.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_game1.png new file mode 100644 index 000000000..84aede49b Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_game1.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_game2.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_game2.png new file mode 100644 index 000000000..58c8690c9 Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_game2.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_hello.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_hello.png new file mode 100644 index 000000000..9f6629b8c Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_hello.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_install1.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_install1.png new file mode 100644 index 000000000..92cc268a3 Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_install1.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_install2.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_install2.png new file mode 100644 index 000000000..14a523cb9 Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_install2.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_plan1.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_plan1.png new file mode 100644 index 000000000..4840d18ed Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_plan1.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_plan2.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_plan2.png new file mode 100644 index 000000000..0b8ad4583 Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_plan2.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_plan3.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_plan3.png new file mode 100644 index 000000000..446b8cc85 Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_plan3.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_plan4.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_plan4.png new file mode 100644 index 000000000..5bc6a7cbe Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_plan4.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_plan5.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_plan5.png new file mode 100644 index 000000000..1c56c0a32 Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_plan5.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_resto_qwen36_1.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_resto_qwen36_1.png new file mode 100644 index 000000000..39d0f8e20 Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_resto_qwen36_1.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_resto_qwen36_2.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_resto_qwen36_2.png new file mode 100644 index 000000000..498d07473 Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_resto_qwen36_2.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/opencode_resto_qwen36_3.png b/oci-vibe-dac-lab/2-hello-game/images/opencode_resto_qwen36_3.png new file mode 100644 index 000000000..484f496ef Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/opencode_resto_qwen36_3.png differ diff --git a/oci-vibe-dac-lab/2-hello-game/images/space-invaders_grok420.png b/oci-vibe-dac-lab/2-hello-game/images/space-invaders_grok420.png new file mode 100644 index 000000000..2f40fbda1 Binary files /dev/null and b/oci-vibe-dac-lab/2-hello-game/images/space-invaders_grok420.png differ diff --git a/oci-vibe-dac-lab/workshops/freetier/index.html b/oci-vibe-dac-lab/workshops/freetier/index.html new file mode 100755 index 000000000..471847eb9 --- /dev/null +++ b/oci-vibe-dac-lab/workshops/freetier/index.html @@ -0,0 +1,63 @@ + + + + + + + + + Oracle LiveLabs + + + + + + + + + + + + + +
+
+
+
+
+
+
+
+ + + + + diff --git a/oci-vibe-dac-lab/workshops/freetier/manifest.json b/oci-vibe-dac-lab/workshops/freetier/manifest.json new file mode 100755 index 000000000..d9f69f2dc --- /dev/null +++ b/oci-vibe-dac-lab/workshops/freetier/manifest.json @@ -0,0 +1,28 @@ +{ + "workshoptitle": "Vibe Code with Open Models on OCI Enterprise AI", + "help": "livelabs-help-oci_us@oracle.com", + "tutorials": [ + { + "title": "Introduction", + "filename": "./../../0-intro/intro.md" + }, + { + "title": "Get Started", + "filename": "https://livelabs.oracle.com/cdn/common/labs/cloud-login/event-register-free-tier-account.md" + }, + { + "title": "Lab 1: Installation", + "filename": "./../../1-install/install.md" + }, + { + "title": "Lab 2: Hello World + Space Invaders", + "filename": "./../../2-hello-game/hello-game.md" + }, + { + "title": "Need Help", + "filename": "https://livelabs.oracle.com/cdn/common/labs/need-help/need-help-freetier.md" + } + ] +} + +