runner_rust/examples/osiris/README.md

OSIRIS Complete Example

A comprehensive end-to-end example demonstrating the complete OSIRIS workflow.

Prerequisites

1. Redis - Must be running on localhost:6379

   redis-server
   

2. Rust - Version 1.88+

   rustup update
   

Complete Example

osiris_complete - Full End-to-End Workflow

ONE EXAMPLE TO RULE THEM ALL - Complete demonstration of OSIRIS.

Run:

cd /Users/timurgordon/code/git.ourworld.tf/herocode/runner_rust
cargo run --example osiris_complete

What it demonstrates:

1. Runner Management - Starts and stops runner_osiris daemon
2. Job Client - Creates client with builder pattern
3. Job Building - Uses JobBuilder for clean job creation
4. Synchronous Execution - Uses run_job() to wait for results
5. OSIRIS Objects - Creates Note and Event objects
6. Context Storage - Stores objects in participant-based contexts
7. Data Querying - Retrieves and lists stored data
8. Access Control - Demonstrates signatory-based access
9. Error Handling - Proper error propagation and cleanup

Expected Output:

🚀 OSIRIS Demo Script
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1: Getting context for participants [alice, bob]
✓ Context ID: alice,bob

Step 2: Creating a Note
✓ Note created with title: Project Planning Meeting
...

Key Concepts

Context Management

Simple Logic:

• Context = list of public keys (participants)
• To get_context, at least one participant must be a signatory
• No state tracking - contexts created fresh each time

Example:

// Signatories: [alice, bob, charlie]

// ✅ Works - alice is a signatory
let ctx = get_context(["alice", "bob"]);

// ❌ Fails - dave is not a signatory
let ctx = get_context(["alice", "dave"]);

OSIRIS Objects

Note:

let note = note("collection_name")
    .title("My Note")
    .content("Note content")
    .tag("key", "value")
    .mime("text/plain");

Event:

let event = event("collection_name")
    .title("My Event")
    .description("Event description")
    .location("Location")
    .tag("type", "meeting");

Context Operations

Save:

let id = ctx.save("collection", "object_id", object);

Get:

let obj = ctx.get("collection", "object_id");

List:

let ids = ctx.list("collection");

Delete:

let deleted = ctx.delete("collection", "object_id");

Query:

let results = ctx.query("collection", "field", "value");

Architecture

┌─────────────────────┐
│   Rhai Script       │
│   (osiris_demo.rhai)│
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  OSIRIS Engine      │
│  - Note API         │
│  - Event API        │
│  - get_context()    │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  OsirisContext      │
│  - Participants     │
│  - CRUD operations  │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│     HeroDB          │
│  (Redis + local DB) │
└─────────────────────┘

Troubleshooting

"Connection refused" on port 6379

• Make sure Redis is running: redis-server
• Check: redis-cli ping (should return "PONG")

"Access denied: none of the participants are signatories"

• Check that at least one participant is in the SIGNATORIES list
• Signatories are set via engine tags (see examples)

"Failed to create context"

• Verify Redis is accessible
• Check HeroDB URL is correct
• Ensure db_id is valid (typically 1)

Next Steps

1. Modify the scripts - Edit osiris_demo.rhai to try different operations
2. Add more objects - Create your own object types
3. Multi-context - Try creating multiple contexts with different participants
4. Integration - Use OSIRIS in your own applications

---

Status: ✅ Ready to Use
Last Updated: 2025-10-24