osiris/RUNNER.md

OSIRIS Runner - Standalone Binary ✅

The OSIRIS runner is a standalone binary that executes Rhai scripts with full OSIRIS object support.

🎉 Status: FULLY OPERATIONAL

✅ Binary created at src/bin/runner/
✅ Rhai engine with OSIRIS objects
✅ Note and Event support
✅ Automatic indexing
✅ Query functionality
✅ Test scripts working

🚀 Quick Start

Run a Script File

cargo run --bin runner --features rhai-support -- runner1 --script-file scripts/test_note.rhai

Run Inline Script

cargo run --bin runner --features rhai-support -- runner1 \
  --script 'let note = note("test").title("Hi"); print(note.get_title());'

📝 Example Output

🚀 OSIRIS Runner
Runner ID: test1
HeroDB: redis://localhost:6379 (DB 1)

📝 Executing script...

─────────────────────────────────────
=== OSIRIS Note Test ===

Creating note...
Note created: Test from OSIRIS Runner
Storing note...
✓ Note stored with ID: 46a064c7-9062-4858-a390-c11f0d5877a7

Retrieving note...
✓ Retrieved: Test from OSIRIS Runner
  Content: This note was created using the OSIRIS standalone runner!

Querying notes by tag...
✓ Found notes:
  - 2c54e1ec-bed9-41ea-851c-f7313abbd7cd
  - 392f3f7f-47e7-444f-ba11-db38d74b12af
  - 46a064c7-9062-4858-a390-c11f0d5877a7
=== Test Complete ===
─────────────────────────────────────

✅ Script completed successfully!

📖 Usage

Command Line Options

OSIRIS Rhai Script Runner

Usage: runner [OPTIONS] <RUNNER_ID>

Arguments:
  <RUNNER_ID>  Runner ID

Options:
  -r, --redis-url <REDIS_URL>
          HeroDB URL [default: redis://localhost:6379]
  -d, --db-id <DB_ID>
          HeroDB database ID [default: 1]
  -s, --script <SCRIPT>
          Script to execute in single-job mode (optional)
  -f, --script-file <SCRIPT_FILE>
          Script file to execute
  -h, --help
          Print help
  -V, --version
          Print version

Script Examples

Create and Store a Note

// scripts/test_note.rhai
let note = note("notes")
    .title("My Note")
    .content("This is the content")
    .tag("project", "osiris")
    .tag("priority", "high");

let id = put_note(note);
print(`Stored: ${id}`);

let retrieved = get_note("notes", id);
print(`Title: ${retrieved.get_title()}`);

Create and Store an Event

// scripts/test_event.rhai
let event = event("calendar", "Team Meeting")
    .description("Weekly sync")
    .location("Conference Room A")
    .category("meetings");

let id = put_event(event);
print(`Event stored: ${id}`);

Query by Index

let ids = query("notes", "tags:tag", "project=osiris");
print("Found notes:");
for id in ids {
    let note = get_note("notes", id);
    print(`  - ${note.get_title()}`);
}

🏗️ Architecture

┌─────────────────────────────────────┐
│   OSIRIS Runner Binary              │
│   (osiris/src/bin/runner/)          │
├─────────────────────────────────────┤
│   ├── main.rs                       │
│   │   - CLI argument parsing        │
│   │   - Script loading              │
│   │   - Execution orchestration     │
│   └── engine.rs                     │
│       - Engine factory              │
│       - OSIRIS integration          │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   OSIRIS Rhai Support               │
│   (osiris/src/rhai_support/)        │
├─────────────────────────────────────┤
│   ├── note_rhai.rs                  │
│   │   - Note CustomType             │
│   │   - Builder methods             │
│   ├── event_rhai.rs                 │
│   │   - Event CustomType            │
│   │   - Builder methods             │
│   └── engine.rs                     │
│       - OsirisRhaiEngine            │
│       - Async → Sync bridge         │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   OSIRIS Core                       │
│   (osiris/src/)                     │
├─────────────────────────────────────┤
│   ├── objects/                      │
│   │   - Note, Event                 │
│   │   - #[derive(DeriveObject)]     │
│   ├── store/                        │
│   │   - GenericStore                │
│   │   - Automatic indexing          │
│   └── index/                        │
│       - FieldIndex                  │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   HeroDB                            │
│   (Redis-compatible storage)        │
└─────────────────────────────────────┘

🎯 Features

1. Fluent Builder Pattern

let note = note("ns")
    .title("Title")
    .content("Content")
    .tag("key", "value");

2. Automatic Indexing

Fields marked with #[index] are automatically indexed:

#[derive(DeriveObject)]
pub struct Note {
    pub base_data: BaseData,
    
    #[index]
    pub title: Option<String>,  // Indexed!
    
    pub content: Option<String>, // Not indexed
    
    #[index]
    pub tags: BTreeMap<String, String>, // Indexed!
}

3. Type-Safe Operations

• Compile-time type checking
• Runtime validation
• Clear error messages

4. Query Support

// Query by any indexed field
let ids = query("namespace", "field_name", "value");

// Query by tag
let ids = query("notes", "tags:tag", "project=osiris");

// Query by title
let ids = query("notes", "title", "My Note");

📚 Available Functions

Note API

Function	Description
note(ns)	Create new note
.title(s)	Set title (chainable)
.content(s)	Set content (chainable)
.tag(k, v)	Add tag (chainable)
.mime(s)	Set MIME type (chainable)
put_note(note)	Store note, returns ID
get_note(ns, id)	Retrieve note by ID
.get_id()	Get note ID
.get_title()	Get note title
.get_content()	Get note content
.to_json()	Serialize to JSON

Event API

Function	Description
event(ns, title)	Create new event
.description(s)	Set description (chainable)
.location(s)	Set location (chainable)
.category(s)	Set category (chainable)
.all_day(b)	Set all-day flag (chainable)
put_event(event)	Store event, returns ID
get_event(ns, id)	Retrieve event by ID
.get_id()	Get event ID
.get_title()	Get event title
.to_json()	Serialize to JSON

Query API

Function	Description
query(ns, field, value)	Query by indexed field, returns array of IDs

🧪 Testing

Test Scripts Included

1. scripts/test_note.rhai - Complete note workflow
2. scripts/test_event.rhai - Complete event workflow

Run Tests

# Test notes
cargo run --bin runner --features rhai-support -- test1 --script-file scripts/test_note.rhai

# Test events
cargo run --bin runner --features rhai-support -- test1 --script-file scripts/test_event.rhai

🔧 Building

Development Build

cargo build --bin runner --features rhai-support

Release Build

cargo build --bin runner --features rhai-support --release

Run Without Cargo

# After building
./target/release/runner runner1 --script-file scripts/test_note.rhai

📦 Integration with runner_rust

The OSIRIS runner can also be integrated into the runner_rust infrastructure for distributed task execution. See runner_rust/src/engine/osiris.rs for the integration.

✅ Verification

Run this to verify everything works:

cargo run --bin runner --features rhai-support -- test1 --script-file scripts/test_note.rhai

Expected output:

✅ Script completed successfully!

🎉 Success!

The OSIRIS runner is fully operational and ready for:

• ✅ Standalone script execution
• ✅ Integration with runner_rust
• ✅ Production use
• ✅ Custom object types (via derive macro)