Merge pull request #45 from oracle-devrel/feature/memory-context-engineering-notebook

Feature/memory context engineering notebook

Author: RichmondAlake

.gitignore

@@ -65,8 +65,14 @@ terraform.rc
 
 # Node
 node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+.npm
+.eslintcache
 
-# Java
+# Java
 .gradle
 build/
 !gradle/wrapper/gradle-wrapper.jar
@@ -75,4 +81,63 @@ build/
 .idea
 bin/
 dist/
-application-local.yaml
+application-local.yaml
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# IDEs
+.vscode/
+*.swp
+*.swo
+*~
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Pre-commit
+.pre-commit-config.yaml.bak
+
+# Build artifacts
+*.min.js
+*.min.css
+*.map
+
+# Logs
+*.log
+logs/
+
+# Temporary files
+*.tmp
+*.temp
+.cache/
+
+# Oracle specific
+*.classpath
+*.project
+.settings/

.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+# Pre-commit hooks configuration
+# See https://pre-commit.com for more information
+
+repos:
+  # Ruff - Fast Python linter and formatter
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.15
+    hooks:
+      # Run the linter
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      # Run the formatter
+      - id: ruff-format
+
+  # Prettier - Code formatter for JavaScript, TypeScript, JSON, YAML, etc.
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        types_or: [javascript, jsx, ts, tsx, json, yaml, markdown]
+        exclude: |
+          (?x)^(
+            .*\.min\.js|
+            .*\.min\.css|
+            node_modules/.*|
+            .*\.lock
+          )$
+
+  # General file checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        args: [--allow-multiple-documents]
+      - id: check-json
+      - id: check-added-large-files
+        args: ["--maxkb=2000"]
+      - id: check-merge-conflict
+      - id: detect-private-key

.prettierignore

@@ -0,0 +1,19 @@
+# Dependencies
+node_modules/
+package-lock.json
+yarn.lock
+
+# Build outputs
+dist/
+build/
+*.min.js
+*.min.css
+
+# Generated files
+*.map
+
+# Lock files
+pnpm-lock.yaml
+
+# Jupyter notebooks (can be formatted separately if needed)
+*.ipynb

.prettierrc

@@ -0,0 +1,11 @@
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "auto"
+}

README.md

@@ -1,19 +1,115 @@
-# OCI Generative AI toolkit
+# Oracle AI Developer Hub
 
-[![License: UPL](https://img.shields.io/badge/license-UPL-green)](https://img.shields.io/badge/license-UPL-green) [![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=oracle-devrel_oci-generative-ai-jet-ui)](https://sonarcloud.io/dashboard?id=oracle-devrel_oci-generative-ai-jet-ui)
+This repository contains technical resources to help AI Developers build AI applications, agents, and systems using Oracle AI Database and OCI services alongside other key components of the AI/Agent stack.
 
+## What You'll Find
 
-## Introduction
+This repository is organized into several key areas:
 
-Using Oracle JET, create a user-friendly prompt-led user interface (UI) to interact with Oracle's new Generative AI service. This toolkit will configure your Generative AI Service connection so you can begin your journey with AI, or migrate your existing (local or Cloud) LLMs to the Oracle AppDev ecosystem.
-[Enhance Engagement Using Content Generation with OCI Generative AI](JET.md)
+### 📱 **Apps** (`/apps`)
 
-This project deploys an AI pipeline with a multipurpose front end for text generation and summarization. The pipeline integrates with a database to track interactions, enabling fine-tuning and performance monitoring for application optimization. It leverages OCI Generative AI APIs on a Kubernetes cluster.
-[Accelerating AI Application Deployment Using Cloud Native Strategies](K8S.md)
+Applications and reference implementations demonstrating how to build AI-powered solutions with Oracle technologies. These complete, working examples showcase end-to-end implementations of AI applications, agents, and systems that leverage Oracle AI Database and OCI services. Each application includes source code, deployment configurations, and documentation to help developers understand architectural patterns, integration approaches, and best practices for building production-grade AI solutions.
+
+| Name                     | Description                                                                                                                       | Link                                                                                                           |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| oci-generative-ai-jet-ui | Full-stack AI application with Oracle JET UI, OCI Generative AI integration, Kubernetes deployment, and Terraform infrastructure | [![View App](https://img.shields.io/badge/View%20App-blue?style=flat-square)](./apps/oci-generative-ai-jet-ui) |
+
+### 📓 **Notebooks** (`/notebooks`)
+
+Jupyter notebooks and interactive tutorials covering:
+
+- AI/ML model development and experimentation
+- Oracle Database AI features and capabilities
+- OCI AI services integration patterns
+- Data preparation and analysis workflows
+- Agent development and orchestration examples
+
+| Name                              | Description                                                                                                                                    | Stack                                         | Link                                                                                                                                           |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| memory_context_engineering_agents | Build AI agents with 6 types of persistent memory. Covers memory engineering, context window management, and just-in-time retrieval patterns. | LangChain, Oracle AI Database, OpenAI, Tavily | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./notebooks/memory_context_engineering_agents.ipynb) |
+| oracle_rag_agents_zero_to_hero    | Learn to build RAG agents from scratch using Oracle AI Database.                                                                               | Oracle AI Database, OpenAI, OpenAI Agents SDK | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./notebooks/oracle_rag_agents_zero_to_hero.ipynb)    |
+| oracle_rag_with_evals             | Build RAG systems with comprehensive evaluation metrics                                                                                        | Oracle AI Database, OpenAI, BEIR, Galileo     | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./notebooks/oracle_rag_with_evals.ipynb)             |
+
+### 🎓 **Workshops** (`/workshops`)
+
+Hands-on workshops and guided learning experiences:
+
+- Step-by-step tutorials for building AI applications
+- End-to-end project walkthroughs
+- Best practices and architectural patterns
+- Integration guides for Oracle AI Database and OCI services
+
+| Name          | Description                  | Link |
+| ------------- | ---------------------------- | ---- |
+| _Coming soon_ | Workshops will be added here | -    |
+
+### 📚 **Guides** (`/guides`)
+
+Comprehensive documentation and reference materials:
+
+- Architecture patterns and design guides
+- API documentation and integration examples
+- Deployment and operations guides
+- Troubleshooting and optimization tips
+- Security and compliance best practices
+
+| Name          | Description               | Link |
+| ------------- | ------------------------- | ---- |
+| _Coming soon_ | Guides will be added here | -    |
+
+### 🤝 **Partners** (`/partners`)
+
+Notebooks and apps contributed by partners in the AI ecosystem. AI Developers can use these resources to understand how to use Oracle AI Database and OCI alongside tools such as LangChain, Galileo, LlamaIndex, and other popular AI/ML frameworks and platforms.
+
+| Name          | Description                                      | Stack | Link |
+| ------------- | ------------------------------------------------ | ----- | ---- |
+| _Coming soon_ | Partner-contributed resources will be added here | -     | -    |
+
+## Getting Started
+
+1. **Explore Applications**: Start with the applications in `/apps` to see complete, working examples
+2. **Follow Workshops**: Check `/workshops` for guided learning paths
+3. **Experiment with Notebooks**: Use `/notebooks` for hands-on experimentation
+4. **Reference Guides**: Consult `/guides` for detailed documentation
+5. **Check Partner Resources**: Explore `/partners` for integrations with popular AI tools and frameworks
 
 ## Contributing
 
-This project is open source.  Please submit your contributions by forking this repository and submitting a pull request!  Oracle appreciates any contributions that are made by the open-source community.
+This project is open source. Please submit your contributions by forking this repository and submitting a pull request! Oracle appreciates any contributions that are made by the open-source community.
+
+### Development Setup
+
+Before contributing, please set up pre-commit hooks to ensure code is automatically formatted:
+
+1. **Install pre-commit**:
+
+   ```bash
+   pip install pre-commit
+   ```
+
+2. **Install additional dependencies** (optional, includes pre-commit and ruff):
+
+   ```bash
+   pip install -r requirements-dev.txt
+   ```
+
+3. **Install pre-commit hooks**:
+
+   ```bash
+   pre-commit install
+   ```
+
+4. **Optional: Format existing code**:
+   ```bash
+   pre-commit run --all-files
+   ```
+
+The pre-commit hooks will automatically format your code using:
+
+- **Ruff** for Python files (formatting and linting)
+- **Prettier** for JavaScript, TypeScript, JSON, YAML, and Markdown files
+
+For more detailed information, see [SETUP_PRE_COMMIT.md](./SETUP_PRE_COMMIT.md).
 
 ## License
 
@@ -23,4 +119,8 @@ Licensed under the Universal Permissive License (UPL), Version 1.0.
 
 See [LICENSE](LICENSE) for more details.
 
-ORACLE AND ITS AFFILIATES DO NOT PROVIDE ANY WARRANTY WHATSOEVER, EXPRESS OR IMPLIED, FOR ANY SOFTWARE, MATERIAL OR CONTENT OF ANY KIND CONTAINED OR PRODUCED WITHIN THIS REPOSITORY, AND IN PARTICULAR SPECIFICALLY DISCLAIM ANY AND ALL IMPLIED WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.  FURTHERMORE, ORACLE AND ITS AFFILIATES DO NOT REPRESENT THAT ANY CUSTOMARY SECURITY REVIEW HAS BEEN PERFORMED WITH RESPECT TO ANY SOFTWARE, MATERIAL OR CONTENT CONTAINED OR PRODUCED WITHIN THIS REPOSITORY. IN ADDITION, AND WITHOUT LIMITING THE FOREGOING, THIRD PARTIES MAY HAVE POSTED SOFTWARE, MATERIAL OR CONTENT TO THIS REPOSITORY WITHOUT ANY REVIEW. USE AT YOUR OWN RISK.
+ORACLE AND ITS AFFILIATES DO NOT PROVIDE ANY WARRANTY WHATSOEVER, EXPRESS OR IMPLIED, FOR ANY SOFTWARE, MATERIAL OR CONTENT OF ANY KIND CONTAINED OR PRODUCED WITHIN THIS REPOSITORY, AND IN PARTICULAR SPECIFICALLY DISCLAIM ANY AND ALL IMPLIED WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE. FURTHERMORE, ORACLE AND ITS AFFILIATES DO NOT REPRESENT THAT ANY CUSTOMARY SECURITY REVIEW HAS BEEN PERFORMED WITH RESPECT TO ANY SOFTWARE, MATERIAL OR CONTENT CONTAINED OR PRODUCED WITHIN THIS REPOSITORY. IN ADDITION, AND WITHOUT LIMITING THE FOREGOING, THIRD PARTIES MAY HAVE POSTED SOFTWARE, MATERIAL OR CONTENT TO THIS REPOSITORY WITHOUT ANY REVIEW. USE AT YOUR OWN RISK.
+
+---
+
+**Note**: This repository is actively maintained and updated with new resources, examples, and best practices for Oracle AI development.

SETUP_PRE_COMMIT.md

@@ -0,0 +1,96 @@
+# Pre-commit Setup Guide
+
+This repository uses pre-commit hooks to automatically format code on every commit.
+
+## Formatters Used
+
+- **Ruff**: Fast Python linter and formatter (replaces Black, isort, and flake8)
+- **Prettier**: Code formatter for JavaScript, TypeScript, JSON, YAML, and Markdown
+
+## Initial Setup
+
+1. **Install dependencies** (if not already installed):
+
+   ```bash
+   pip install -r requirements-dev.txt
+   ```
+
+   Or install individually:
+
+   ```bash
+   pip install pre-commit ruff
+   ```
+
+2. **Install pre-commit hooks**:
+
+   ```bash
+   pre-commit install
+   ```
+
+   This will set up the git hooks to run automatically on every commit.
+
+3. **Optional: Run on all files** (to format existing code):
+   ```bash
+   pre-commit run --all-files
+   ```
+
+## How It Works
+
+Once installed, pre-commit will automatically:
+
+- Format Python code with Ruff before each commit
+- Format JavaScript/TypeScript/JSON/YAML/Markdown files with Prettier
+- Check for trailing whitespace, end-of-file issues, and other common problems
+- Prevent committing if there are formatting issues
+
+## Manual Usage
+
+You can also run the formatters manually:
+
+```bash
+# Run all hooks on staged files
+pre-commit run
+
+# Run all hooks on all files
+pre-commit run --all-files
+
+# Run a specific hook
+pre-commit run ruff --all-files
+pre-commit run prettier --all-files
+```
+
+## Configuration Files
+
+- `.pre-commit-config.yaml`: Pre-commit hooks configuration
+- `pyproject.toml`: Ruff configuration (Python formatting and linting)
+- `.prettierrc`: Prettier configuration (JavaScript/TypeScript formatting)
+- `.prettierignore`: Files to exclude from Prettier formatting
+
+## Updating Hooks
+
+To update pre-commit hooks to their latest versions:
+
+```bash
+pre-commit autoupdate
+```
+
+## Troubleshooting
+
+If hooks fail, you can:
+
+1. **Skip hooks for a specific commit** (not recommended):
+
+   ```bash
+   git commit --no-verify
+   ```
+
+2. **Update hook versions**:
+
+   ```bash
+   pre-commit autoupdate
+   ```
+
+3. **Clear pre-commit cache**:
+   ```bash
+   pre-commit clean
+   ```