Merge branch 'main' into 185-langchain-mcp-export

Author: corradodebari

.github/workflows/pytest.yml

@@ -7,6 +7,7 @@ on:
       - opened
       - synchronize
       - reopened
+      - ready_for_review
 
   # Allows running this workflow manually
   workflow_dispatch:

README.md

@@ -85,10 +85,14 @@ To run the application in a container; download the [source](https://github.com/
 1. [Configure](https://oracle-samples.github.io/ai-optimizer/client/configuration/index.html) the **AI Optimizer**.
 
 #### Got OCI?
-The **AI Optimizer** can be deployed with an Oracle Autonomous Database 23ai using infrastructure as code.  Deploy the **AI Optimizer** in Oracle Cloud Infrastructure using OCI Resource Manager:
 
+The **AI Optimizer** can be deployed in Oracle Cloud Infrastructure (OCI) using Infrastructure as Code (IaC).
+
+Choose either a light-weight Virtual Machine or robust Oracle Kubernetes Engine deployment, both with an Oracle Autonomous Database 23ai:  
 [![Deploy to Oracle Cloud][magic_button]][magic_arch_stack]
 
+For more information, please visit the [IaC Documentation](https://oracle-samples.github.io/ai-optimizer/advanced/iac/index.html).
+
 ## Contributing
 
 This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md).

docs/content/_index.md

@@ -51,7 +51,7 @@ The [Walkthrough](walkthrough) is a great way to familiarize yourself with the *
 
 ### Bare-Metal Installation
 
-To run the application on bare-metal; download the [source]({{ .Site.Params.GitHubRepo }}) and from the `src/` directory:
+To run the application on bare-metal; download the source code from the {{< latest_release >}} and from the `src/` directory:
 
 1. Create and activate a Python Virtual Environment:
 
@@ -84,7 +84,7 @@ To run the application on bare-metal; download the [source]({{ .Site.Params.GitH
 References to `podman` commands, if applicable to your environment, can be substituted with `docker`.
 {{% /notice %}}
 
-To run the application in a container; download the [source]({{ .Site.Params.GitHubRepo }}) and from the top-level directory:
+To run the application in a container; download the source code from the {{< latest_release >}} and from the top-level directory:
 
 1. Build the image.
 

docs/content/advanced/iac.md

@@ -0,0 +1,86 @@
++++
+title = 'Infrastructure as Code'
+weight = 1
++++
+
+<!--
+Copyright (c) 2024, 2025, Oracle and/or its affiliates.
+Licensed under the Universal Permissive License v1.0 as shown at http://oss.oracle.com/licenses/upl.
+
+spell-checker: ignore opentofu Ollama
+-->
+
+The {{< full_app_ref >}} can easily be deployed in Oracle Cloud Infrastructure (**OCI**) using Infrastructure as Code (**IaC**) provided in the source [opentofu](https://github.com/oracle-samples/ai-optimizer/tree/main/opentofu) directory.
+
+Choose between deploying a light-weight [Virtual Machine](#virtual-machine) or robust [Oracle Kubernetes Engine (**OKE**)](#oracle-kubernetes-engine) along with the Oracle Autonomous Database for a fully configured {{< short_app_ref >}} environment, ready to use.  
+
+While the **IaC** can be run from a command-line with prior experience, the steps outlined here use [Oracle Cloud Resource Manager](https://docs.oracle.com/en-us/iaas/Content/ResourceManager/Concepts/resourcemanager.htm) to simplify the process.  To get started:
+
+{{< imagelink url="https://cloud.oracle.com/resourcemanager/stacks/create?zipUrl=https://github.com/oracle-samples/ai-optimizer/releases/latest/download/ai-optimizer-stack.zip" src="https://oci-resourcemanager-plugin.plugins.oci.oraclecloud.com/latest/deploy-to-oracle-cloud.svg" alt="Deploy to Oracle Cloud" >}}
+
+## Virtual Machine
+
+The Virtual Machine (VM) deployment provisions both the {{< short_app_ref >}} API Server and GUI Client together in an "All-in-One" configuration for experimentation and development.  As part of the deployment, one local Large Language Model and one Embedding Model is made available out-of-the-box.  However, as these models will be running on a CPU VM, their performance will be very poor.
+
+### Configure Variables
+
+After clicking the "Deploy to Oracle Cloud" button and authenticating to your tenancy; you will be presented with the {{< short_app_ref >}} stack information.
+
+1. Review the Terms, tick the box to accept (if you do), and click "Next" to Configure Variables
+
+    ![Stack Information](../images/iac_stack_information.png)
+
+1. Change the Infrastructure to "VM"
+
+    ![Stack - AI Optimizer](../images/iac_stack_optimizer.png)
+
+#### Access Control
+
+Most of the other configuration options are self-explanatory, but let's highlight those important for the **Security** of your deployment.
+
+* The {{< short_app_ref >}} is often configured with authentication details for your OCI Tenancy, Autonomous Database, and API Keys for AI Models. Since these details are accessible via the Application GUI, access must be restricted to a limited set of CIDR blocks.
+
+* The {{< short_app_ref >}} REST endpoints require API token authentication, providing some protection. However, you should still restrict access to a limited set of CIDR blocks where possible for added security.
+
+* The Oracle Autonomous Database requires mTLS authentication with a wallet, providing strong initial protection. However, it's recommended to further restrict access to a limited set of CIDR blocks.
+
+![Stack - Access Control](../images/iac_stack_access_control.png)
+
+To restrict access, provide a comma-separated list of CIDR blocks, for example: `192.168.1.0/24,10.0.0.0/16,203.0.113.42/32`
+
+In this example:
+* `192.168.1.0/24` – Allows access from all IPs in the range 192.168.1.0 to 192.168.1.255 (a typical subnet).
+* `10.0.0.0/16` – Allows access from 10.0.0.0 to 10.0.255.255 (a broader range).
+* `203.0.113.42/32` – Allows access from a single public IP address only. The /32 denotes a single host.
+
+### Review and Apply
+
+After configuring the variables, click "Next" to review and apply the stack.
+
+![Stack - Review and Apply](../images/iac_stack_review_apply.png)
+
+Tick the Apply box and click "Create".
+
+### Job Details
+
+The next screen will show the progress of the Apply job.  Once the job has Succeeded, the {{< short_app_ref >}} has been deployed!
+
+The Application Information tab will provide the URL's to access the {{< short_app_ref >}} GUI and API Server.  In the "All-in-One" deployment on the VM, the API Server will only become accessible after visiting the GUI at least once.
+
+![Stack - VM Application Information](../images/iac_stack_vm_info.png)
+
+{{% notice style="code" title="502 Bad Gateway: Communication Breakdown!" icon="fire" %}}
+Although the infrastructure is deployed, the {{< short_app_ref >}} may still be initializing, which can result in a 502 Bad Gateway error when accessing the URLs. Please allow up to 10 minutes for the configuration to complete.
+{{% /notice %}}
+
+To get a better understanding of how the API Server works and to obtain the API Key for making REST calls, review the [API Server documentation](client/api_server/).
+
+### Cleanup
+
+To destroy the {{< short_app_ref >}} infrastructure, in **OCI** navigate to `Developer Services` -> `Stacks`.  Choose the Compartment the {{< short_app_ref >}} was deployed into and select the stack Name.  Click on the "Destroy" button.
+
+## Oracle Kubernetes Engine
+
+{{% notice style="code" title="Documentation is Hard!" icon="circle-info" %}}
+More information coming soon... 11-June-2025
+{{% /notice %}}