diff --git a/ai/generative-ai-service/a-getting-started-guide/README.md b/ai/generative-ai-service/a-getting-started-guide/README.md index 40e6c4f0d..25fd799c4 100644 --- a/ai/generative-ai-service/a-getting-started-guide/README.md +++ b/ai/generative-ai-service/a-getting-started-guide/README.md @@ -43,9 +43,33 @@ Deploy an OpenAI-compatible gateway that proxies requests to OCI GenAI, configur **[Read the guide →](files/N8N-GenAIOCI-Connection.md)** +### Guide 4 — Cline + Oracle Code Assist + +**VS Code Extension (Agent)** that autonomously manages the file system, terminal, and browser to execute multi-step engineering tasks. + +**[Read the guide →](files/Cline-OCA-Connection.md)** + +### Guide 5 — Codex + Oracle Code Assist + +**VS Code Extension (Agent)** that reads, edits, and runs code in your workspace to autonomously build applications and fix bugs. + +**[Read the guide →](files/Codex-OCA-Connection.md)** + +### Guide 6 — Aider + Oracle Code Assist + +**Command-Line Tool (Agent)** that enables conversational code editing and refactoring directly within a local git repository. + +**[Read the guide →](files/Aider-OCA-Connection.md)** + +### Guide 7 — Kilo + Oracle Code Assist + +**JetBrains Plugin (Agent)** that provides an autonomous workflow within IntelliJ to plan, write, and debug code across multiple files. + +**[Read the guide →](files/Kilo-OCA-Connection.md)** + ### Common Prerequisites -All three guides share the same foundational setup: +All three GenAI service guides share the same foundational setup: 1. An active OCI tenancy with Generative AI enabled 2. IAM policies granting access to `generative-ai-family` @@ -53,6 +77,12 @@ All three guides share the same foundational setup: Each guide then adds tool-specific requirements (Python packages, LangChain, n8n, etc.). +All guides relating to Oracle Code Assist share the following setup: + +1. Request access to [Oracle Code Assist Models](https://confluence.oraclecorp.com/confluence/display/AICODE/How+to+Request+Entitlements+for+Oracle+Code+Assist+Models) +2. Find the most up-to-date information on [Oracle Code Assist](https://oracle.sharepoint.com/sites/ai-for-employees/SitePages/Oracle-Code-Assist.aspx) +3. Ask for further help in the `#oracle-code-assist-users` slack channel + ### File Structure ``` . @@ -61,7 +91,12 @@ Each guide then adds tool-specific requirements (Python packages, LangChain, n8n └── files/ ├── OracleDB-GenAIOCI-Connection.md # Guide 1 – OCI SDK + Oracle DB 26ai ├── LangChainOCI-GenAIOCI-Connection.md # Guide 2 – LangChain integration - └── N8N-GenAIOCI-Connection.md # Guide 3 – n8n / low-code integration + ├── N8N-GenAIOCI-Connection.md # Guide 3 – n8n / low-code integration + ├── Cline-OCA-Connection.md # Guide 4 – Cline + Oracle Code Assist + ├── Codex-OCA-Connection.md # Guide 5 – Codex + Oracle Code Assist + ├── Aider-OCA-Connection.md # Guide 6 – Aider + Oracle Code Assist + └── Kilo-OCA-Connection.md # Guide 7 – Kilo + Oracle Code Assist + ``` # Useful Links @@ -70,6 +105,8 @@ Each guide then adds tool-specific requirements (Python packages, LangChain, n8n - [OCI Generative AI — LangChain Integration](https://docs.oracle.com/en-us/iaas/Content/generative-ai/langchain.htm) - [OCI IAM Policies — Getting Started](https://docs.oracle.com/en-us/iaas/Content/Identity/Concepts/policygetstarted.htm) - [OCI API Key Authentication Setup](https://docs.oracle.com/en-us/iaas/Content/generative-ai/setup-oci-api-auth.htm) +- [Oracle Code Assist Tutorials](https://oracle.sharepoint.com/sites/ai-for-employees/SitePages/Oracle-Code-Assist.aspx) +- [Oracle Code Assist Models Request](https://confluence.oraclecorp.com/confluence/display/AICODE/How+to+Request+Entitlements+for+Oracle+Code+Assist+Models) # License diff --git a/ai/generative-ai-service/a-getting-started-guide/files/Aider-OCA-Connection.md b/ai/generative-ai-service/a-getting-started-guide/files/Aider-OCA-Connection.md new file mode 100644 index 000000000..3fa3ec3d6 --- /dev/null +++ b/ai/generative-ai-service/a-getting-started-guide/files/Aider-OCA-Connection.md @@ -0,0 +1,61 @@ +# Aider Integration with Oracle Code Assist (OCA) +Aider is a command-line tool (CLI) that leverages AI to help developers modify and write code. It enables users to chat with AI directly from their terminal, allowing for code edits, suggestions, and explanations in their project files through conversational interaction. Aider integrates with local Git repositories, making it easy to review and manage code changes proposed by the AI.  + +## Key Features +* Interactive code editing with AI suggestions and explanations  +* Works changes and integrates with Git for version control  +* Can automate code refactoring, documentation, bug fixes, and more  + +## Resources +* Request [access](https://confluence.oraclecorp.com/confluence/display/AICODE/How+to+Request+Entitlements+for+Oracle+Code+Assist+Models) to OCA +* Download the latest [OCA on Aider client](https://oracle.sharepoint.com/:f:/r/sites/ai-for-employees/Shared%20Documents/AI%20for%20Engineers/Plugin%20Downloads/Aider%20-%20CLI?csf=1\&web=1\&e=aPt5Ra) +* View [OCA on Aider guide](https://oracle.sharepoint.com/:f:/r/sites/ai-for-employees/Shared%20Documents/AI%20for%20Engineers/Installation%20Guides?csf=1\&web=1\&e=ylt36M) for **detailed setup instructions** +* For more information, please visit the [Aider website](https://aider.chat/docs/) + +## Step-by-Step Guide +### 1. **Request Access to OCA Models** +* Prior to installation, request entitlements for the desired OCA models by following the guide in the PDF (e.g., via Oracle's internal process). This grants access to Oracle's AI models within Aider. + +### 2. **Install Aider (ocaider)** +* Download the latest `ocaider_chat-0.1.3-py3-none-any.whl` file from the provided Oracle [SharePoint link](https://oracle.sharepoint.com/sites/ai-for-employees/Shared%20Documents/Forms/AllItems.aspx?csf=1&web=1&e=cwasJL&CID=b1be9fa4%2D6ac6%2D4e2d%2D9eef%2D58fde111effc&FolderCTID=0x01200008E7535C0D00CD448E4A8499AAC8B8AE&id=%2Fsites%2Fai%2Dfor%2Demployees%2FShared%20Documents%2FAI%20for%20Engineers%2FPlugin%20Downloads%2FAider%20%2D%20CLI). + +* **Option 1: Install with uv (Recommended for Python 3.8-3.13)**: + * Install uv if needed: `python -m pip install uv`. + * Run: `uv tool install --force --python python3.12 --with pip ocaider_chat-0.1.3-py3-none-any.whl`. + * This handles Python versioning automatically. + +* **Option 2: Install with pipx (For Python 3.9-3.12)**: + * Install pipx if needed: `python -m pip install pipx`. + * Run: `pipx install ocaider_chat-0.1.3-py3-none-any.whl`. + +### 3. **Basic Setup and Model Selection** +* Launch Aider: Run `ocaider` in your terminal from your project's Git repository directory. +* **Before Starting**: List available models with `ocaider --list-models oca` and select an OCA model (e.g., `ocaider --model oca/gpt-4.1`). is the default and only recommended provider; avoid others. +* **During Runtime**: Use in-chat commands like `/models oca` to list and `/model oca/openai-o3` to switch models. + +### 4. **General Usage and Key Commands** +* Add files to edit: Include them on the command line (e.g., `ocaider file1.py file2.js`) or use `/add filename` in-chat. Aider auto-includes related context; avoid adding unnecessary files to prevent token overload. + +* Interact conversationally: Describe tasks (e.g., "Refactor this function"). Aider suggests edits, integrates with Git for reviews, and tracks changes. + +* Essential Commands: + * `/help`: List commands or get dynamic help (e.g., `/help What is the best way to use Aider?`). + * `/ask`: Switch to query-only mode without editing files. + * `/code`: Default mode for code modifications. + * `/architect`: For high-level task guidance. + * `/clear`: Reset chat history; `/drop`: Remove files from context. + * `!` or `/run`: Execute terminal commands (e.g., `!git status`). + * Reference code elements: Type file/method names for autocomplete and context. + +* Include Rules/Conventions: Load a file like `CONVENTIONS.md` with `--read` on startup or `/read` in-chat for persistent guidance. + +### 5. **Advanced Tips** +* **Verbose Mode**: Run `ocaider --verbose` for detailed logs of AI interactions if responses seem off. +* **IDE Integration**: Use `--watch-files` to monitor repo files for AI comments (e.g., `# Make a snake game. AI!` triggers edits; `AI?` asks questions). +* Work in your project's Git repo for seamless version control. + +### 6. **Troubleshooting** +* For issues, run `/opc-request-id` to get the request ID and include it when reporting to the OCA team (attach chat history). +* Common fixes: Ensure Git integration, limit file additions, or check Python compatibility. Refer to the PDF's troubleshooting section or Aider docs for errors like model access or command failures. + +This setup enables terminal-based AI coding assistance with OCA, focusing on secure, compliant use at Oracle. Always select only Oracle providers. For advanced coding support,. offers enhanced tools. join the `#oracle-code-assist-users` Slack channel for more info. diff --git a/ai/generative-ai-service/a-getting-started-guide/files/Cline-OCA-Connection.md b/ai/generative-ai-service/a-getting-started-guide/files/Cline-OCA-Connection.md new file mode 100644 index 000000000..2020f3f47 --- /dev/null +++ b/ai/generative-ai-service/a-getting-started-guide/files/Cline-OCA-Connection.md @@ -0,0 +1,42 @@ +# Cline Integration with Oracle Code Assist (OCA) +Cline is an autonomous coding agent, integrated as a plugin into Visual Studio Code (VS Code) that enhances developer productivity. Oracle Code Assist is available as a model provider on Cline, which gives Oracle developers secure access to Oracle-approved large language models (LLMs) with built-in protections for open-source code license scanning and content moderation. + +## Key Features +* Reads and writes files across your entire code repository +* Executes terminal commands and debugs errors  +* Plans complex features before writing code  +* Connects to external systems through MCP servers  +* Understands large code projects with intelligent context management + +## Resources +* Request [access](https://confluence.oraclecorp.com/confluence/display/AICODE/How+to+Request+Entitlements+for+Oracle+Code+Assist+Models) to OCA +* View [OCA on Cline for VS Code](https://oracle.sharepoint.com/sites/ai-for-employees/SitePages/Oracle-Code-Assist.aspx) for **detailed setup instructions**. +* For more information, please visit the [Cline website](https://docs.cline.bot/getting-started/what-is-cline) + +## Step-by-Step Guide +### 1. **Request Access to OCA Models** +- Before installation, request entitlements for the desired OCA models. This ensures you can access Oracle's AI models through Cline. + +### 2. **Install Cline Extension in VS Code** +- Open VS Code. +- Go to the Extensions view (left sidebar icon). +- Search for "Cline" in the Marketplace. +- Install the Cline extension from the publisher and trust it when prompted. + +### 3. **Post-Install Setup** +- Launch Cline from the VS Code sidebar. +- Select "Use your own API key" to begin configuration. +- Choose "Oracle Code Assist" as the API Provider from the dropdown (it's the recommended and default option for Oracle users). +- Log in via Oracle SSO: Click "Login with Oracle SSO." If a browser popup doesn't open, manually add "*.oraclecloud.com" to your trusted domains in VS Code settings, then retry. + +### 4. **Configure Model Selection (Optional but Recommended)** +- Click the gear icon in Cline to access settings. +- Use the model dropdown to select or refresh available OCA models (avoid selecting non-Oracle providers). +- Acknowledge any data restrictions or disclaimers as prompted. + +### 5. **Test and Troubleshoot** +- Start a new chat in Cline to verify functionality. +- If issues arise (e.g., VPN proxy errors, login failures, or network issues), check the Troubleshooting section in [OCA on Cline for VS Code ](https://oracle.sharepoint.com/sites/ai-for-employees/Shared%20Documents/AI%20for%20Engineers/Installation%20Guides/Oracle%20Code%20Assist%20on%20Cline%20for%20VS%20Code.pdf?CT=1759188695679\&OR=ItemsView). Common fixes include updating endpoints for VPNs, adding no-proxy URLs in VS Code settings, or forwarding ports for remote SSH. +- For remote SSH or multi-instance setups, ensure single VS Code instances and proper port forwarding (e.g., port 8669 to localhost). + +This setup unlocks OCA's AI capabilities in VS Code for coding assistance. If you encounter enterprise-specific restrictions (e.g., VPNs like Cerner), consult Oracle's internal guidelines for compliance. For advanced coding support, consider Oracle Code Assist tools via the `#oracle-code-assist-users` Slack channel. diff --git a/ai/generative-ai-service/a-getting-started-guide/files/Codex-OCA-Connection.md b/ai/generative-ai-service/a-getting-started-guide/files/Codex-OCA-Connection.md new file mode 100644 index 000000000..0fce60649 --- /dev/null +++ b/ai/generative-ai-service/a-getting-started-guide/files/Codex-OCA-Connection.md @@ -0,0 +1,56 @@ +# Codex Integration with Oracle Code Assist (OCA) +Codex is an AI coding assistant, integrated as a plugin into Visual Studio Code (VS Code), that accelerates development with context‑aware code generation and in‑editor assistance. + +## Key Features +* Provides context‑aware inline code completions and multi‑line suggestions +* Converts natural language prompts into code (functions, snippets, SQL, regex) +* Explains code and errors; proposes fixes, refactors, tests, and documentation +* Adapts to project context (open files and recent edits) across many languages and frameworks +* Fits seamlessly into VS Code workflows with quick accept/edit flows and chat‑based assistance + +## Resources +* Request [access](https://confluence.oraclecorp.com/confluence/display/AICODE/How+to+Request+Entitlements+for+Oracle+Code+Assist+Models) to OCA +* View [OCA on Codex ](https://oracle.sharepoint.com/sites/ai-for-employees/SitePages/Oracle-Code-Assist.aspx)for **detailed setup instructions** +* For more information, please visit: [developers.openai.com/codex/ide](https://developers.openai.com/codex/ide/) + +## Step-by-Step Guide +#### 1. **Prerequisites** +* Request access to OCA API Key and specific models (e.g., via the "[How to Request Entitlements for Oracle Code Assist Models](https://confluence.oraclecorp.com/confluence/display/AICODE/How+to+Request+Entitlements+for+Oracle+Code+Assist+Models)" guide). Without these, you'll encounter errors. +* For Windows users, consider using Windows Subsystem for Linux (WSL) for Codex CLI compatibility. + +#### 2. **Install Codex CLI** +* Download and install Codex CLI from the official OpenAI site: [https://developers.openai.com/codex/cli/ ](https://developers.openai.com/codex/cli/). +* Create a `.codex` folder in your home directory if it doesn't exist. +* Download the OCA-specific `config.toml` file (overwrite/create it in `~/.codex/`) with the provided content from the [Codex Setup PDF](https://oracle.sharepoint.com/sites/ai-for-employees/SitePages/Oracle-Code-Assist.aspx). This includes OCA endpoints, model providers (e.g., `oca-responses`, `oca-chat`), and profiles for models like `gpt-5-codex`, `grok-4`, etc. Key settings: Set `model = "oca/gpt-5-codex"` and `profile = "gpt-5-codex"` as defaults; enable `web_search_request = true` and `trust_level = "trusted"`. +* Generate an OCA API Key: Visit [https://apex.oraclecorp.com/pls/apex/r/oca/api-key/home ](https://apex.oraclecorp.com/pls/apex/r/oca/api-key/home), generate the key, and copy the "Codex Environment Setup Command" (e.g., `echo | codex login --with-api-key`). Run it in your terminal. + * **Important**: The API Key expires every 7 days; regenerate weekly to avoid errors. + +#### 3. **Run and Configure Codex CLI** +* Launch with the default profile: Run `codex` in your terminal (uses `gpt-5-codex` by default). +* Avoid running `/review` or other commands without OCA config; redownload if needed. +* Change Models: Edit `~/.codex/config.toml` to update `model` and `profile` (e.g., `model = "oca/grok-code-fast-1"` and `profile = "grok-code-fast-1"`). Then run `codex -p ` (e.g., `codex -p grok-code-fast-1`). Restart the session for changes to apply. Request access if a model is unavailable. +* Interact: Use conversational prompts for code tasks; Codex integrates with your local workspace and Git for edits and reviews. + +#### 4. **Install Codex IDE Extension in VS Code (Optional, Builds on CLI)** +* **Prerequisites**: Complete Codex CLI installation first, as the extension relies on it. +* In VS Code, go to Extensions > Search for "Codex" > Install "Codex - OpenAI's coding agent". +* Generate/Regenerate OCA API Key as in Step 2 (weekly refresh required). +* Configure the Extension: + * Open the Codex sidebar in VS Code. + * Click the gear icon > "Sign in with ChatGPT" > "Use API Key." + * Paste your OCA API Key and proceed through setup screens. + +* The extension uses the default CLI profile (`gpt-5-codex`); changes won't apply dynamically; edit `~/.codex/config.toml` as in Step 3 and restart VS Code. + +#### 5. **Test and Troubleshoot** +* In CLI: Run `codex` and test a simple prompt (e.g., code generation). In VS Code: Open the chat window and query OCA models. + +* Common Issues and Fixes: + * Errors like "no access to default model": Switch profiles (e.g., `codex -p gpt-5`) or request entitlements. + * Login/API failures: Regenerate the API Key; ensure OCA-specific config is loaded. + * Model changes not applying: Restart the tool/session and verify `config.toml`. + * For advanced config (e.g., approval policies, sandbox mode), refer to [https://developers.openai.com/codex/config-advanced](https://developers.openai.com/codex/config-advanced). + +* Always use OCA profiles/models; avoid external ones for compliance. + +This setup allows secure, OCA-powered coding in your terminal or VS Code, emphasizing local execution and Git integration. Adhere to Oracle's data policies. For complex coding tasks, gentle reminder: Oracle Code Assist offers advanced AI-powered coding support; join the `#oracle-code-assist-users` Slack channel for more information. diff --git a/ai/generative-ai-service/a-getting-started-guide/files/Kilo-OCA-Connection.md b/ai/generative-ai-service/a-getting-started-guide/files/Kilo-OCA-Connection.md new file mode 100644 index 000000000..6f8aba841 --- /dev/null +++ b/ai/generative-ai-service/a-getting-started-guide/files/Kilo-OCA-Connection.md @@ -0,0 +1,51 @@ +# Kilo Integration with Oracle Code Assist (OCA) +Kilo is an autonomous coding agent, integrated as a plugin into IntelliJ that enhances developer productivity. Oracle Code Assist is available as a model provider on Kilo, which gives Oracle developers secure access to Oracle-approved large language models (LLMs) with built-in protections for open-source code license scanning and content moderation. + +## Key Features +* Reads and writes files across your entire code repository +* Executes terminal commands and debugs errors  +* Plans complex features before writing code  +* Connects to external systems through MCP servers  +* Understands large code projects with intelligent context management + +## Resources +* Request [access](https://oracle.sharepoint.com/sites/ai-for-employees/SitePages/Oracle-Code-Assist.aspx) OCA +* View [OCA on Kilo Code for IntelliJ](https://oracle.sharepoint.com/sites/ai-for-employees/SitePages/Oracle-Code-Assist.aspx) for **detailed setup instructions** +* For more information visit: https://kilocode.ai/docs  + +## Step-by-Step Guide +### 1. **Request Access to OCA Models** +* Before proceeding, request entitlements for the desired OCA models using the guide in the PDF (e.g., via Oracle's internal process). This enables access to Oracle's AI models through Kilocode. + +### 2. **Prerequisites** +* Ensure Node.js version 20.6.0 or higher is installed on your machine (macOS, Windows, or Linux). Verify with `node -v` and `which node`. +* If needed, install or update Node.js (e.g., via `brew install node` on macOS or nvm). For proxy users, ensure the path points to the correct version. + +### 3. **Download and Install Kilocode Plugin** +* Download the latest Kilocode binary (e.g., `Kilo Code-0.0.1.zip`) from the latest version specified in the `OCA on Kilo Code for IntelliJ PDF` +* Do **not** install from the marketplace; uninstall any existing marketplace version if present. +* Go to Settings > Plugins > Gear icon > "Install Plugin from Disk" > Select the downloaded ZIP > Apply > OK. +* Disable auto-updates in plugin settings to prevent overwrites from external sources. +* Kilocode icon appears in the sidebar; click it to open. It may initialize for up to a minute. + +### 4. **Post-Install Setup** +* In the Kilocode window, select "Use your own API key." +* Change the API Provider to "Oracle Code Assist" (the only recommended option; avoid others). +* Click "Login with Oracle SSO" and complete authentication. If login fails (e.g., due to proxy or trusted domains), remove PAC/WPAD references from IntelliJ proxy settings and set proxies via environment variables (e.g., in `.zshrc`). +* After login, select a model from the dropdown (request access if empty). Click "Let's Go" to start. + +### 5. **Configure Model Selection (Optional but Recommended)** +* Click the gear icon in Kilocode settings. +* Use the model dropdown to view or refresh available OCA models. +* Acknowledge any data restrictions or disclaimers (especially for OpenAI models). + +### 6. **Test and Troubleshoot** +* Open a project and interact with Kilocode (e.g., prompt for code suggestions). +* Common Issues and Fixes: + * "Node.js environment missing" or endless initialization: Run `sudo rm /usr/local/bin/node` followed by `ln -s "$(which node)" /usr/local/bin/node`, then restart IntelliJ. + * SSO login errors: Ensure no PAC files (e.g., `http://wpad/wpad.dat`) in proxy settings; use environment variables only. + * Full reset: Kill IntelliJ processes and clear JetBrains caches/directories as outlined in [OCA on Kilo Code for IntelliJ](https://oracle.sharepoint.com/sites/ai-for-employees/Shared%20Documents/Forms/AllItems.aspx?viewid=523d1542-44f5-4efc-b685-82d6467c3829&id=/sites/ai-for-employees/Shared%20Documents/AI%20for%20Engineers/Installation%20Guides/Oracle%20Code%20Assist%20on%20Kilocode.pdf&parent=/sites/ai-for-employees/Shared%20Documents/AI%20for%20Engineers/Installation%20Guides) + +* For proxy/VPN users, verify Node.js path and proxy configurations. + +This setup integrates OCA's AI features into IntelliJ for secure coding support. Always use only Oracle providers for compliance. If this is a complex coding task, gentle reminder: Oracle Code Assist offers advanced AI-powered coding support. check the `#oracle-code-assist-users` Slack channel for more details.