sync: update from internal GitLab repository

Content updated:

Files:
- module.xml

Directories:
- docs/
- objectscript/

Synced at: 2025-08-04 08:05:35

Author: tom-dyar

docs/OBJECTSCRIPT_SYNTAX_LEARNING_REPORT.md

@@ -0,0 +1,235 @@
+# ObjectScript Syntax Learning Report
+## Expert Changes Analysis: Benjamin De Boe
+
+*Based on analysis of commits 47757a1 and 90a6e6b*
+
+---
+
+## 🎯 Executive Summary
+
+This report analyzes critical ObjectScript syntax improvements made by InterSystems expert Benjamin De Boe that resolved compilation failures in the IRIS RAG Templates project. These changes demonstrate essential ObjectScript best practices and modern syntax patterns that should be committed to memory for improved ObjectScript development skills.
+
+## 📋 Key Learning Categories
+
+### 1. **Method Return Statements** 
+**Critical Learning: Use `return` instead of `Quit` in modern ObjectScript**
+
+#### ❌ Old Pattern (Problematic):
+```objectscript
+ClassMethod InvokeBasicRAG(query As %String) As %String
+{
+    Try {
+        Set result = bridge."invoke_basic_rag"(query, config)
+        Quit result  // ❌ Old syntax
+    } Catch ex {
+        Set error = {"success": (false)}
+        Quit error.%ToJSON()  // ❌ Old syntax
+    }
+}
+```
+
+#### ✅ New Pattern (Expert Fix):
+```objectscript
+ClassMethod InvokeBasicRAG(query As %String) As %String
+{
+    Try {
+        Set result = bridge."invoke_basic_rag"(query, config)
+        return result  // ✅ Modern syntax
+    } Catch ex {
+        Set error = {"success": false}
+        return error.%ToJSON()  // ✅ Modern syntax
+    }
+}
+```
+
+**Learning Point**: Modern ObjectScript prefers `return` statements over `Quit` for method returns. This improves readability and follows contemporary InterSystems development standards.
+
+---
+
+### 2. **Boolean Values in JSON Objects**
+**Critical Learning: Remove unnecessary parentheses around boolean values**
+
+#### ❌ Old Pattern (Problematic):
+```objectscript
+Set error = {
+    "success": (false),  // ❌ Unnecessary parentheses
+    "result": null,
+    "error": (ex.DisplayString())
+}
+```
+
+#### ✅ New Pattern (Expert Fix):
+```objectscript
+Set error = {
+    "success": false,  // ✅ Clean boolean syntax
+    "result": null,
+    "error": (ex.DisplayString())  // ✅ Parentheses only where needed (function calls)
+}
+```
+
+**Learning Point**: In ObjectScript JSON objects, boolean values should be written directly as `true` or `false` without parentheses. Parentheses are only needed around function calls or complex expressions.
+
+---
+
+### 3. **Property Naming Conventions with Database Mapping**
+**Critical Learning: Use camelCase properties with SqlFieldName attributes**
+
+#### ❌ Old Pattern (Problematic):
+```objectscript
+/// Document identifier
+Property doc_id As %String(MAXLEN = 255) [ Required ];
+
+/// Full text content
+Property text_content As %Stream.GlobalCharacter;
+
+/// Creation timestamp  
+Property created_at As %TimeStamp [ InitialExpression = {$ZDateTime($Horolog,3)} ];
+
+/// Index on document ID
+Index DocIdIndex On doc_id [ Unique ];
+```
+
+#### ✅ New Pattern (Expert Fix):
+```objectscript
+/// Document identifier
+Property docid As %String(MAXLEN = 255) [ Required, SqlFieldName = "doc_id" ];
+
+/// Full text content
+Property textcontent As %Stream.GlobalCharacter [ SqlFieldName = "text_content" ];
+
+/// Creation timestamp
+Property createdat As %TimeStamp [ InitialExpression = {$ZDateTime($Horolog,3)}, SqlFieldName = "created_at" ];
+
+/// Index on document ID (using new property name)
+Index DocIdIndex On docid [ Unique ];
+```
+
+**Learning Point**: ObjectScript best practice is to use camelCase property names in class definitions while maintaining database compatibility through `SqlFieldName` attributes. This provides clean ObjectScript syntax while preserving expected database field names.
+
+---
+
+## 🔧 Technical Patterns to Remember
+
+### A. **SqlFieldName Attribute Pattern**
+```objectscript
+// Standard pattern for database field mapping
+Property camelCaseName As %DataType [ SqlFieldName = "snake_case_db_field" ];
+
+// Real examples from expert fixes:
+Property docid As %String(MAXLEN = 255) [ Required, SqlFieldName = "doc_id" ];
+Property textcontent As %Stream.GlobalCharacter [ SqlFieldName = "text_content" ];
+Property createdat As %TimeStamp [ SqlFieldName = "created_at" ];
+```
+
+### B. **Index Definition Updates**
+```objectscript
+// When property names change, update index definitions accordingly
+Index DocIdIndex On docid [ Unique ];        // ✅ Uses new camelCase property name
+Index CreatedAtIndex On createdat;           // ✅ Uses new camelCase property name
+```
+
+### C. **Modern Method Structure**
+```objectscript
+ClassMethod MethodName() As %String
+{
+    Try {
+        // Main logic here
+        return successResult;  // ✅ Use 'return'
+    } Catch ex {
+        Set error = {
+            "success": false,  // ✅ No parentheses around booleans
+            "error": (ex.DisplayString())  // ✅ Parentheses for function calls
+        }
+        return error.%ToJSON();  // ✅ Use 'return'
+    }
+}
+```
+
+---
+
+## 🎓 Key Takeaways for ObjectScript Development
+
+### 1. **Method Returns**
+- **Always use `return`** instead of `Quit` in modern ObjectScript
+- Improves code readability and follows current InterSystems standards
+- Consistent with other modern programming languages
+
+### 2. **JSON Object Syntax**
+- **Remove parentheses** around simple boolean values (`true`, `false`)
+- **Keep parentheses** around function calls and complex expressions
+- Cleaner, more readable JSON object definitions
+
+### 3. **Property Naming Strategy**
+- **Use camelCase** for ObjectScript property names
+- **Add SqlFieldName attributes** to maintain database compatibility
+- **Update all references** including index definitions
+- Best of both worlds: clean ObjectScript code + database compatibility
+
+### 4. **Database Compatibility**
+- SqlFieldName attributes allow property names to differ from database field names
+- Enables ObjectScript naming conventions while preserving existing database schemas
+- Critical for projects with established database structures
+
+---
+
+## 🚀 Impact Assessment
+
+### Before Expert Changes:
+- ❌ **Compilation Failures**: GitHub CI failing due to syntax issues
+- ❌ **Mixed Conventions**: Inconsistent use of `Quit` vs `return`
+- ❌ **Verbose JSON**: Unnecessary parentheses around boolean values
+- ❌ **Database Constraints**: Property names forced to match database field names
+
+### After Expert Changes:
+- ✅ **Clean Compilation**: All ObjectScript classes compile successfully
+- ✅ **Modern Syntax**: Consistent use of `return` statements
+- ✅ **Clean JSON**: Proper boolean syntax in JSON objects
+- ✅ **Best Practice**: camelCase properties with SqlFieldName mapping
+
+---
+
+## 📝 Practical Application Guidelines
+
+### When Writing New ObjectScript Classes:
+1. **Always use `return`** for method returns
+2. **Use camelCase** for property names
+3. **Add SqlFieldName** attributes for database mapping
+4. **Write clean JSON** without unnecessary parentheses
+5. **Update indexes** to reference new property names
+
+### When Reviewing ObjectScript Code:
+1. **Check for `Quit` statements** → Replace with `return`
+2. **Look for `(false)` or `(true)`** → Simplify to `false` or `true`
+3. **Verify property naming** → Ensure camelCase with SqlFieldName mapping
+4. **Validate index references** → Ensure they use correct property names
+
+---
+
+## 🎯 Memory Commits for ObjectScript Excellence
+
+**Remember these expert patterns:**
+
+```objectscript
+// ✅ Perfect ObjectScript method structure
+ClassMethod ExampleMethod() As %String {
+    Try {
+        // Main logic
+        return result;
+    } Catch ex {
+        Set error = {"success": false, "error": (ex.DisplayString())}
+        return error.%ToJSON();
+    }
+}
+
+// ✅ Perfect property definition with database mapping
+Property camelCaseName As %DataType [ SqlFieldName = "database_field_name" ];
+
+// ✅ Perfect index definition
+Index NameIndex On camelCaseName [ Unique ];
+```
+
+These patterns, when consistently applied, produce clean, modern, and compilation-ready ObjectScript code that follows InterSystems best practices.
+
+---
+
+*Report compiled by analyzing expert ObjectScript improvements made by Benjamin De Boe on August 4, 2025*

module.xml

@@ -1,18 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <Export generator="IRIS" version="26">
-  <Document name="iris-rag.ZPM">
-    <Module>
-      <Name>iris-rag</Name>
-      <Version>0.2.0</Version>
-      <Description>A comprehensive, production-ready framework for implementing Retrieval Augmented Generation (RAG) pipelines using InterSystems IRIS as the vector database backend.</Description>
-      <Keywords>RAG,Vector Search,Machine Learning,AI,IRIS,Python,Embeddings</Keywords>
-      <Packaging>module</Packaging>
-      <SourcesRoot>objectscript</SourcesRoot>
-      <Resource Name="RAG.PKG"/>
-      
-      <!-- Dependencies -->
-      <Dependencies>
-      </Dependencies>
-    </Module>
-  </Document>
+  <!-- Simple IRIS export without ZPM dependencies -->
+  <Class name="RAG.SourceDocumentsWithIFind">
+    <Super>%Persistent</Super>
+    <TimeStamp>65432,12345.123456</TimeStamp>
+  </Class>
+  <Class name="RAG.IFindSetup">
+    <TimeStamp>65432,12345.123456</TimeStamp>
+  </Class>
+  <Class name="RAG.SourceDocumentsFixed">
+    <Super>%Persistent</Super>
+    <TimeStamp>65432,12345.123456</TimeStamp>
+  </Class>
 </Export>