Skip to content

Commit 8bd5477

Browse files
tom-dyartom-dyar
committed
sync: update from internal GitLab repository
Content updated: Files: - README.md - module.xml Directories: - iris_rag/ - docs/ - scripts/ - objectscript/ - tests/ Synced at: 2025-08-02 16:54:00
1 parent bddb268 commit 8bd5477

16 files changed

+335
-438
lines changed

‎README.md

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -52,10 +52,22 @@ make quick-start # Guided setup wizard
5252

5353
## 🚀 Quick Start
5454

55-
### 🆓 Free Community Edition
55+
### 🆓 Free Community Edition (Default)
5656
**This project uses InterSystems IRIS Community Edition by default - completely free, no license required!**
5757

58-
All Docker configurations (`docker-compose.yml`, `docker-compose.iris-only.yml`) use `intersystemsdc/iris-community:latest` for immediate, license-free usage. For Enterprise Edition features, see `docker-compose.licensed.yml`.
58+
All Docker configurations (`docker-compose.yml`, `docker-compose.iris-only.yml`) use `intersystemsdc/iris-community:latest` for immediate, license-free usage.
59+
60+
**Community vs Enterprise Edition:**
61+
- **Community Edition** (Default): Free, full RAG functionality, perfect for development and production
62+
- **Enterprise Edition**: Licensed version with additional enterprise features (use `docker-compose.licensed.yml`)
63+
64+
```bash
65+
# Start with Community Edition (default)
66+
docker-compose up -d
67+
68+
# Or use the standalone Community Edition configuration
69+
docker-compose -f docker-compose.iris-only.yml up -d
70+
```
5971

6072
### One-Command Setup
6173
Get started with a complete RAG system in minutes using our intelligent setup wizard:
@@ -290,7 +302,7 @@ make quick-start-status # Check system health and configuration
290302

291303
## 🌟 Key Features
292304

293-
- **🆓 Free to Use**: Default IRIS Community Edition setup - no license required
305+
- **🆓 Free Community Edition**: Default setup uses IRIS Community Edition - completely free, no license required
294306
- **🚀 One-Command Setup**: Complete RAG systems in minutes with intelligent profiles
295307
- **🎯 Profile-Based Configuration**: Minimal, Standard, Extended - optimized for every use case
296308
- **🔧 Interactive CLI Wizard**: Guided setup with validation and intelligent defaults

‎docs/IPM_INSTALLATION.md

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
# IPM Installation Guide
2+
3+
## Installing via InterSystems Package Manager (IPM/ZPM)
4+
5+
This guide covers installing the RAG Templates package using InterSystems Package Manager (IPM) directly in your IRIS instance.
6+
7+
## Prerequisites
8+
9+
- InterSystems IRIS 2025.1 or later
10+
- IPM/ZPM installed in your IRIS instance
11+
- Internet access for downloading dependencies
12+
- Python 3.11+ available on the system
13+
14+
## Installation Methods
15+
16+
### Method 1: From Package Manager Registry
17+
18+
```objectscript
19+
// Install from IPM registry
20+
zpm "install intersystems-iris-rag"
21+
```
22+
23+
### Method 2: From GitHub Repository
24+
25+
```objectscript
26+
// Install directly from GitHub
27+
zpm "install https://github.com/intersystems-community/iris-rag-templates"
28+
```
29+
30+
### Method 3: From Local Module
31+
32+
1. Clone the repository:
33+
```bash
34+
git clone https://github.com/intersystems-community/iris-rag-templates.git
35+
cd iris-rag-templates
36+
```
37+
38+
2. Install via IPM:
39+
```objectscript
40+
// In IRIS Terminal
41+
zpm "load /path/to/iris-rag-templates/"
42+
```
43+
44+
## Installation Parameters
45+
46+
The package supports several configuration parameters:
47+
48+
| Parameter | Description | Default | Options |
49+
|-----------|-------------|---------|---------|
50+
| `PYTHON_PATH` | Path to Python executable | `python3` | Any valid Python path |
51+
| `INSTALL_PYTHON_PACKAGE` | Install Python dependencies | `1` | `0` (skip), `1` (install) |
52+
| `ENABLE_VECTOR_SEARCH` | Enable IRIS Vector Search | `1` | `0` (disable), `1` (enable) |
53+
| `NAMESPACE` | Target installation namespace | `USER` | Any valid namespace |
54+
55+
### Custom Installation with Parameters
56+
57+
```objectscript
58+
// Install with custom parameters
59+
zpm "install intersystems-iris-rag -DParameters=""PYTHON_PATH=/usr/local/bin/python3,NAMESPACE=MYRAG"""
60+
```
61+
62+
## Post-Installation Configuration
63+
64+
### 1. Verify Installation
65+
66+
```objectscript
67+
// Check installation status
68+
Do ##class(RAG.IPMInstaller).Test()
69+
```
70+
71+
### 2. Configure Python Environment
72+
73+
If automatic Python installation was skipped, manually configure:
74+
75+
```bash
76+
# Navigate to installation directory
77+
cd /path/to/iris-installation/
78+
79+
# Install Python dependencies
80+
pip install -r requirements.txt
81+
```
82+
83+
### 3. Initialize Vector Search
84+
85+
```objectscript
86+
// Enable vector search capabilities
87+
Do ##class(RAG.VectorMigration).EnableVectorSearch()
88+
```
89+
90+
### 4. Test RAG Functionality
91+
92+
```objectscript
93+
// Test basic RAG functionality
94+
Set bridge = ##class(RAG.PythonBridge).%New()
95+
Set result = bridge.Query("What is machine learning?", "basic")
96+
Write result.answer
97+
```
98+
99+
## Python Integration
100+
101+
### Environment Setup
102+
103+
The package automatically configures Python integration, but you may need to verify:
104+
105+
```python
106+
# Test Python package import
107+
import iris_rag
108+
from rag_templates import RAG
109+
110+
# Initialize RAG system
111+
rag = RAG()
112+
result = rag.query("test query")
113+
print(result)
114+
```
115+
116+
### Configuration Files
117+
118+
After installation, the following configuration files are available:
119+
120+
- `config/config.yaml` - Main configuration
121+
- `config/pipelines.yaml` - Pipeline configurations
122+
- `requirements.txt` - Python dependencies
123+
- `pyproject.toml` - Package metadata
124+
125+
## Verification Steps
126+
127+
### 1. Database Schema Verification
128+
129+
```objectscript
130+
// Check if RAG tables were created
131+
SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
132+
WHERE TABLE_SCHEMA = 'RAG'
133+
```
134+
135+
### 2. Python Package Verification
136+
137+
```python
138+
# Verify all RAG pipelines are available
139+
from iris_rag.validation.factory import get_available_pipelines
140+
pipelines = get_available_pipelines()
141+
print(f"Available pipelines: {pipelines}")
142+
```
143+
144+
### 3. ObjectScript Integration Verification
145+
146+
```objectscript
147+
// Test ObjectScript-Python bridge
148+
Set demo = ##class(RAGDemo.TestBed).%New()
149+
Do demo.RunBasicTests()
150+
```
151+
152+
## Troubleshooting
153+
154+
### Common Issues
155+
156+
**1. Python Import Errors**
157+
```bash
158+
# Ensure Python path is correct
159+
which python3
160+
pip list | grep sentence-transformers
161+
```
162+
163+
**2. Vector Search Not Enabled**
164+
```objectscript
165+
// Enable vector search manually
166+
Do ##class(RAG.VectorMigration).EnableVectorSearch()
167+
```
168+
169+
**3. Missing Dependencies**
170+
```bash
171+
# Reinstall Python dependencies
172+
pip install -r requirements.txt --force-reinstall
173+
```
174+
175+
**4. Namespace Issues**
176+
```objectscript
177+
// Switch to correct namespace
178+
zn "USER"
179+
// Or your target namespace
180+
zn "MYRAG"
181+
```
182+
183+
### Diagnostic Commands
184+
185+
```objectscript
186+
// Run comprehensive diagnostics
187+
Do ##class(RAG.IPMInstaller).ValidateInstallation()
188+
189+
// Check system status
190+
Do ##class(RAG.IPMInstaller).GetSystemStatus()
191+
192+
// Test individual components
193+
Do ##class(RAG.IPMInstaller).TestPythonIntegration()
194+
Do ##class(RAG.IPMInstaller).TestVectorSearch()
195+
Do ##class(RAG.IPMInstaller).TestRAGPipelines()
196+
```
197+
198+
## Uninstallation
199+
200+
To remove the package:
201+
202+
```objectscript
203+
// Uninstall package
204+
zpm "uninstall intersystems-iris-rag"
205+
```
206+
207+
This will:
208+
- Remove ObjectScript classes
209+
- Clean up database schema (optional)
210+
- Remove package metadata
211+
212+
Note: Python dependencies and configuration files may need manual cleanup.
213+
214+
## Advanced Configuration
215+
216+
### Custom Schema Installation
217+
218+
```objectscript
219+
// Install to custom schema
220+
Do ##class(RAG.IPMInstaller).SetParameter("CUSTOM_SCHEMA", "MyCompany")
221+
Do ##class(RAG.IPMInstaller).Configure()
222+
```
223+
224+
### Production Deployment
225+
226+
For production environments:
227+
228+
1. **Set Production Parameters**:
229+
```objectscript
230+
Do ##class(RAG.IPMInstaller).SetParameter("ENVIRONMENT", "PRODUCTION")
231+
Do ##class(RAG.IPMInstaller).SetParameter("LOG_LEVEL", "WARNING")
232+
```
233+
234+
2. **Configure Security**:
235+
```objectscript
236+
// Set up secure database connections
237+
Do ##class(RAG.IPMInstaller).ConfigureProductionSecurity()
238+
```
239+
240+
3. **Enable Monitoring**:
241+
```objectscript
242+
// Enable production monitoring
243+
Do ##class(RAG.IPMInstaller).EnableMonitoring()
244+
```
245+
246+
## Support and Documentation
247+
248+
- **Main Documentation**: [RAG Templates Documentation](../README.md)
249+
- **Configuration Guide**: [Configuration Documentation](CONFIGURATION.md)
250+
- **Troubleshooting**: [Deployment Guide](guides/DEPLOYMENT_GUIDE.md)
251+
- **API Reference**: [Developer Guide](DEVELOPER_GUIDE.md)
252+
253+
## Version Compatibility
254+
255+
| RAG Templates Version | IRIS Version | Python Version | Notes |
256+
|----------------------|--------------|----------------|-------|
257+
| 0.2.0+ | 2025.1+ | 3.11+ | Full feature support |
258+
| 0.1.x | 2024.1+ | 3.9+ | Limited vector search |
259+
260+
For older IRIS versions, consider manual installation following the [Deployment Guide](guides/DEPLOYMENT_GUIDE.md).

‎iris_rag/utils/ipm_integration.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ class IPMIntegration:
1616

1717
def __init__(self):
1818
self.package_name = "intersystems-iris-rag"
19-
self.version = "0.1.0"
19+
self.version = "0.2.0"
2020

2121
def validate_environment(self) -> Dict[str, Any]:
2222
"""

‎module.xml

Lines changed: 58 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,69 @@
66
<Version>0.2.0</Version>
77
<Description>A comprehensive, production-ready framework for implementing Retrieval Augmented Generation (RAG) pipelines using InterSystems IRIS as the vector database backend.</Description>
88
<Keywords>RAG,Vector Search,Machine Learning,AI,IRIS,Python,Embeddings</Keywords>
9+
<Author>InterSystems Developer Community</Author>
10+
<License>MIT</License>
11+
<Repository>https://github.com/intersystems-community/iris-rag-templates</Repository>
12+
<Homepage>https://github.com/intersystems-community/iris-rag-templates</Homepage>
13+
<MinimumVersion>2025.1</MinimumVersion>
14+
15+
<!-- Configuration Parameters -->
16+
<Parameter Name="PYTHON_PATH">
17+
<Description>Path to Python executable for RAG operations</Description>
18+
<Default>python3</Default>
19+
</Parameter>
20+
<Parameter Name="INSTALL_PYTHON_PACKAGE">
21+
<Description>Whether to install Python dependencies during setup</Description>
22+
<Default>1</Default>
23+
</Parameter>
24+
<Parameter Name="ENABLE_VECTOR_SEARCH">
25+
<Description>Enable IRIS Vector Search capabilities</Description>
26+
<Default>1</Default>
27+
</Parameter>
28+
<Parameter Name="NAMESPACE">
29+
<Description>Target namespace for installation</Description>
30+
<Default>USER</Default>
31+
</Parameter>
32+
33+
<!-- Dependencies -->
34+
<Dependencies>
35+
<ModuleReference>
36+
<Name>iris-python-tools</Name>
37+
<Version>1.0.0</Version>
38+
<Optional>true</Optional>
39+
</ModuleReference>
40+
</Dependencies>
41+
42+
<!-- Package Resources -->
943
<Packaging>module</Packaging>
1044
<SourcesRoot>objectscript</SourcesRoot>
45+
46+
<!-- ObjectScript Classes -->
1147
<Resource Name="RAG.IPMInstaller.CLS"/>
1248
<Resource Name="RAG.VectorMigration.CLS"/>
1349
<Resource Name="RAG.IFindSetup.CLS"/>
14-
<Resource Name="enable_vector_search.cos"/>
15-
<Resource Name="python_bridge.py"/>
50+
<Resource Name="RAG.PythonBridge.CLS"/>
51+
<Resource Name="RAG.SourceDocumentsWithIFind.CLS"/>
52+
<Resource Name="RAGDemo.Invoker.CLS"/>
53+
<Resource Name="RAGDemo.KeywordFinder.CLS"/>
54+
<Resource Name="RAGDemo.KeywordProcessor.CLS"/>
55+
<Resource Name="RAGDemo.TestBed.CLS"/>
56+
57+
<!-- Python Package Resources -->
58+
<Resource Name="iris_rag" Directory="iris_rag" Recurse="true"/>
59+
<Resource Name="rag_templates" Directory="rag_templates" Recurse="true"/>
60+
<Resource Name="common" Directory="common" Recurse="true"/>
61+
<Resource Name="requirements.txt"/>
62+
<Resource Name="pyproject.toml"/>
63+
<Resource Name="README.md"/>
64+
65+
<!-- Installation Lifecycle -->
66+
<Lifecycle>
67+
<Setup>RAG.IPMInstaller.Setup</Setup>
68+
<Configure>RAG.IPMInstaller.Configure</Configure>
69+
<Activate>RAG.IPMInstaller.Activate</Activate>
70+
<Test>RAG.IPMInstaller.Test</Test>
71+
</Lifecycle>
1672
</Module>
1773
</Document>
1874
</Export>

0 commit comments

Comments
 (0)