runner_rust/README_OSIRIS.md

# OSIRIS Rhai Engine Integration

This module provides Rhai scripting support for OSIRIS objects, allowing you to create, store, and retrieve Notes, Events, and other OSIRIS objects using Rhai scripts.

## Setup

### 1. Add OSIRIS Dependency

Add to `Cargo.toml`:

```toml
[dependencies]
osiris = { path = "../osiris", features = ["rhai-support"] }
```

### 2. Update the Engine

Uncomment the OSIRIS integration code in `src/engine/osiris.rs`:

```rust
use osiris::rhai_support::{register_note_api, register_event_api, OsirisRhaiEngine};

pub fn create_osiris_engine(
    herodb_url: &str,
    db_id: u16,
) -> Result<Engine, Box<dyn std::error::Error>> {
    let mut engine = Engine::new();
    
    // Create OSIRIS engine wrapper
    let osiris_engine = OsirisRhaiEngine::new(herodb_url, db_id)?;
    
    // Register Note API
    register_note_api(&mut engine);
    
    // Register Event API  
    register_event_api(&mut engine);
    
    // Register OSIRIS storage methods
    osiris_engine.register_in_engine(&mut engine);
    
    Ok(engine)
}
```

## Usage

### Rhai Script Example

```rhai
// Create a note with builder pattern
let note = note("notes")
    .title("My Note")
    .content("This is the content")
    .tag("topic", "rust")
    .tag("project", "osiris")
    .mime("text/plain");

// Store the note
let id = put_note(note);
print(`Note stored with ID: ${id}`);

// Retrieve the note
let retrieved = get_note("notes", id);
print(`Title: ${retrieved.get_title()}`);
print(`Content: ${retrieved.get_content()}`);

// Query by tag
let ids = query("notes", "tags:tag", "project=osiris");
print(`Found ${ids.len()} notes`);

for note_id in ids {
    let n = get_note("notes", note_id);
    print(`  - ${n.get_title()}`);
}
```

### Rust Example

```rust
use runner_rust::engine::osiris::run_osiris_script;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let script = r#"
        let note = note("notes")
            .title("Hello from Rhai")
            .content("This works!")
            .tag("source", "rhai");
        
        let id = put_note(note);
        print(`Stored: ${id}`);
    "#;
    
    run_osiris_script(script, "redis://localhost:6379", 1)?;
    Ok(())
}
```

## Available Functions

### Note Functions

- **`note(namespace: String) -> Note`** - Create a new note
- **`.title(title: String) -> Note`** - Set title (chainable)
- **`.content(content: String) -> Note`** - Set content (chainable)
- **`.tag(key: String, value: String) -> Note`** - Add tag (chainable)
- **`.mime(mime: String) -> Note`** - Set MIME type (chainable)
- **`put_note(note: Note) -> String`** - Store note, returns ID
- **`get_note(ns: String, id: String) -> Note`** - Retrieve note by ID
- **`.get_id() -> String`** - Get note ID
- **`.get_title() -> String`** - Get note title
- **`.get_content() -> String`** - Get note content
- **`.to_json() -> String`** - Serialize to JSON

### Event Functions

- **`event(namespace: String, title: String) -> Event`** - Create a new event
- **`.description(desc: String) -> Event`** - Set description (chainable)
- **`.location(location: String) -> Event`** - Set location (chainable)
- **`.category(category: String) -> Event`** - Set category (chainable)
- **`.all_day(all_day: bool) -> Event`** - Set all-day flag (chainable)
- **`put_event(event: Event) -> String`** - Store event, returns ID
- **`get_event(ns: String, id: String) -> Event`** - Retrieve event by ID
- **`.get_id() -> String`** - Get event ID
- **`.get_title() -> String`** - Get event title
- **`.to_json() -> String`** - Serialize to JSON

### Query Functions

- **`query(ns: String, field: String, value: String) -> Array`** - Query by indexed field
  - Returns array of IDs matching the query
  - Example: `query("notes", "tags:tag", "project=osiris")`

## Examples

See:
- `examples/osiris_script.rhai` - Complete Rhai script example
- `examples/osiris_example.rs` - Rust integration example

## Running Examples

```bash
# Start HeroDB first
cd /path/to/herodb
cargo run --release -- --dir ./data --admin-secret mysecret --port 6379

# Run the example
cd /path/to/runner_rust
cargo run --example osiris_example
```

## Architecture

```
Rhai Script
    ↓
OSIRIS Rhai Engine (runner_rust/src/engine/osiris.rs)
    ↓
OSIRIS Rhai Support (osiris/src/rhai_support/)
    ├── note_rhai.rs (Note CustomType + builder API)
    ├── event_rhai.rs (Event CustomType + builder API)
    └── engine.rs (OsirisRhaiEngine wrapper)
    ↓
OSIRIS Core (osiris/src/)
    ├── objects/ (Note, Event)
    ├── store/ (GenericStore, HeroDbClient)
    └── index/ (FieldIndex)
    ↓
HeroDB (Redis-compatible storage)
```

## Benefits

1. **Fluent Builder Pattern**: Chain method calls for clean, readable scripts
2. **Type Safety**: Rhai's type system ensures correct usage
3. **Async Bridge**: Sync Rhai scripts can use async OSIRIS operations
4. **Automatic Indexing**: Objects are automatically indexed based on `#[index]` attributes
5. **Familiar Syntax**: Rhai syntax is similar to JavaScript/Rust

## Next Steps

1. Add `osiris` dependency to `Cargo.toml`
2. Uncomment the integration code in `src/engine/osiris.rs`
3. Run the examples
4. Create your own Rhai scripts!