osiris/EXAMPLES.md

OSIRIS Examples

This document provides practical examples of using OSIRIS for various use cases.

Prerequisites

1. Start HeroDB:

cd /path/to/herodb
cargo run --release -- --dir ./data --admin-secret mysecret --port 6379

2. Build OSIRIS:

cd /path/to/osiris
cargo build --release

3. Initialize OSIRIS:

./target/release/osiris init --herodb redis://localhost:6379

---

Example 1: Personal Note Management

Create a namespace for notes

./target/release/osiris ns create notes

Add notes with tags

# Create a note about Rust
echo "Rust is a systems programming language focused on safety and performance." | \
  ./target/release/osiris put notes/rust-intro - \
  --title "Introduction to Rust" \
  --tags topic=rust,level=beginner,type=tutorial \
  --mime text/plain

# Create a note about OSIRIS
echo "OSIRIS is an object storage system built on HeroDB." | \
  ./target/release/osiris put notes/osiris-overview - \
  --title "OSIRIS Overview" \
  --tags topic=osiris,level=intermediate,type=documentation \
  --mime text/plain

# Create a note from a file
./target/release/osiris put notes/network-latency ./network-notes.md \
  --title "Network Latency Analysis" \
  --tags topic=networking,priority=high,type=analysis \
  --mime text/markdown

Search notes

# Search for notes about Rust
./target/release/osiris find "rust" --ns notes

# Filter by tag
./target/release/osiris find --ns notes --filter topic=rust

# Combine text search and filters
./target/release/osiris find "performance" --ns notes --filter level=beginner

# Get more results
./target/release/osiris find "programming" --ns notes --topk 20

# Output as JSON
./target/release/osiris find "rust" --ns notes --json

Retrieve notes

# Get note as JSON (with metadata)
./target/release/osiris get notes/rust-intro

# Get raw content only
./target/release/osiris get notes/rust-intro --raw

# Save to file
./target/release/osiris get notes/rust-intro --raw --output /tmp/rust-intro.txt

Delete notes

./target/release/osiris del notes/rust-intro

---

Example 2: Calendar/Event Management

Create a calendar namespace

./target/release/osiris ns create calendar

Add events

# Add a meeting
echo '{"title":"Team Standup","when":"2025-10-20T10:00:00Z","attendees":["alice","bob"]}' | \
  ./target/release/osiris put calendar/standup-2025-10-20 - \
  --title "Team Standup" \
  --tags type=meeting,team=eng,priority=high \
  --mime application/json

# Add a deadline
echo '{"title":"Project Deadline","when":"2025-10-31T23:59:59Z","project":"osiris-mvp"}' | \
  ./target/release/osiris put calendar/deadline-osiris - \
  --title "OSIRIS MVP Deadline" \
  --tags type=deadline,project=osiris,priority=critical \
  --mime application/json

# Add a reminder
echo '{"title":"Code Review","when":"2025-10-21T14:00:00Z","pr":"#123"}' | \
  ./target/release/osiris put calendar/review-pr123 - \
  --title "Code Review PR #123" \
  --tags type=reminder,team=eng \
  --mime application/json

Search events

# Find all meetings
./target/release/osiris find --ns calendar --filter type=meeting

# Find high-priority items
./target/release/osiris find --ns calendar --filter priority=high

# Search by text
./target/release/osiris find "standup" --ns calendar

# Find project-specific events
./target/release/osiris find --ns calendar --filter project=osiris

---

Example 3: Code Snippet Library

Create a snippets namespace

./target/release/osiris ns create snippets

Add code snippets

# Rust snippet
cat > /tmp/rust-error-handling.rs <<'EOF'
use anyhow::Result;

fn main() -> Result<()> {
    let result = risky_operation()?;
    println!("Success: {}", result);
    Ok(())
}

fn risky_operation() -> Result<String> {
    Ok("All good!".to_string())
}
EOF

./target/release/osiris put snippets/rust-error-handling /tmp/rust-error-handling.rs \
  --title "Rust Error Handling with anyhow" \
  --tags language=rust,topic=error-handling,pattern=result \
  --mime text/x-rust

# Python snippet
cat > /tmp/python-async.py <<'EOF'
import asyncio

async def fetch_data(url):
    await asyncio.sleep(1)
    return f"Data from {url}"

async def main():
    result = await fetch_data("https://example.com")
    print(result)

asyncio.run(main())
EOF

./target/release/osiris put snippets/python-async /tmp/python-async.py \
  --title "Python Async/Await Example" \
  --tags language=python,topic=async,pattern=asyncio \
  --mime text/x-python

Search snippets

# Find all Rust snippets
./target/release/osiris find --ns snippets --filter language=rust

# Find async patterns
./target/release/osiris find "async" --ns snippets

# Find error handling examples
./target/release/osiris find --ns snippets --filter topic=error-handling

---

Example 4: Document Management

Create a documents namespace

./target/release/osiris ns create docs

Add documents

# Add a specification
./target/release/osiris put docs/osiris-spec ./docs/specs/osiris-mvp.md \
  --title "OSIRIS MVP Specification" \
  --tags type=spec,project=osiris,status=draft \
  --mime text/markdown

# Add a README
./target/release/osiris put docs/readme ./README.md \
  --title "OSIRIS README" \
  --tags type=readme,project=osiris,status=published \
  --mime text/markdown

# Add meeting notes
echo "# Team Meeting 2025-10-20\n\n- Discussed OSIRIS MVP\n- Decided on minimal feature set" | \
  ./target/release/osiris put docs/meeting-2025-10-20 - \
  --title "Team Meeting Notes" \
  --tags type=notes,date=2025-10-20,team=eng \
  --mime text/markdown

Search documents

# Find all specifications
./target/release/osiris find --ns docs --filter type=spec

# Find draft documents
./target/release/osiris find --ns docs --filter status=draft

# Search by content
./target/release/osiris find "MVP" --ns docs

---

Example 5: Multi-Namespace Operations

List all namespaces

./target/release/osiris ns list

Get statistics

# Overall stats
./target/release/osiris stats

# Namespace-specific stats
./target/release/osiris stats --ns notes
./target/release/osiris stats --ns calendar
./target/release/osiris stats --ns snippets

Delete a namespace

./target/release/osiris ns delete snippets

---

Example 6: Batch Operations

Bulk import notes

# Create multiple notes from a directory
for file in ./my-notes/*.md; do
  filename=$(basename "$file" .md)
  ./target/release/osiris put "notes/$filename" "$file" \
    --tags source=import,format=markdown \
    --mime text/markdown
done

Export all notes

# Get all note IDs and export them
./target/release/osiris find --ns notes --topk 1000 --json | \
  jq -r '.[].id' | \
  while read id; do
    ./target/release/osiris get "notes/$id" --raw --output "./export/$id.txt"
  done

---

Example 7: Advanced Search Patterns

Complex filtering

# Find high-priority engineering tasks
./target/release/osiris find --ns calendar \
  --filter priority=high \
  --filter team=eng

# Find beginner-level Rust tutorials
./target/release/osiris find "rust" --ns notes \
  --filter level=beginner \
  --filter type=tutorial

Combining text search with filters

# Find notes about "performance" tagged as high priority
./target/release/osiris find "performance" --ns notes \
  --filter priority=high

# Find meetings about "standup"
./target/release/osiris find "standup" --ns calendar \
  --filter type=meeting

---

Example 8: JSON Output and Scripting

Get search results as JSON

# Search and process with jq
./target/release/osiris find "rust" --ns notes --json | \
  jq '.[] | {id: .id, score: .score, snippet: .snippet}'

# Count results
./target/release/osiris find "programming" --ns notes --json | \
  jq 'length'

# Get top result
./target/release/osiris find "osiris" --ns notes --json | \
  jq '.[0]'

Scripting with OSIRIS

#!/bin/bash
# Script to find and display all high-priority items

echo "High Priority Items:"
echo "==================="

# Search notes
echo -e "\nNotes:"
./target/release/osiris find --ns notes --filter priority=high --json | \
  jq -r '.[] | "- \(.id): \(.snippet)"'

# Search calendar
echo -e "\nEvents:"
./target/release/osiris find --ns calendar --filter priority=high --json | \
  jq -r '.[] | "- \(.id): \(.snippet)"'

---

Tips and Best Practices

1. Consistent Tagging

Use consistent tag names across your objects:

# Good: consistent tag names
--tags topic=rust,level=beginner,type=tutorial

# Avoid: inconsistent naming
--tags Topic=Rust,skill_level=Beginner,kind=Tutorial

2. Meaningful IDs

Use descriptive IDs that make sense:

# Good: descriptive ID
./target/release/osiris put notes/rust-ownership-guide ...

# Avoid: cryptic ID
./target/release/osiris put notes/abc123 ...

3. Use MIME Types

Always specify MIME types for better organization:

--mime text/markdown
--mime application/json
--mime text/x-rust
--mime text/plain

4. Leverage Filters

Use filters to narrow down search results:

# Instead of searching all notes
./target/release/osiris find "rust" --ns notes

# Filter by specific criteria
./target/release/osiris find "rust" --ns notes --filter level=beginner

5. Regular Backups

Export your data regularly:

# Export all namespaces
for ns in notes calendar docs; do
  ./target/release/osiris find --ns "$ns" --topk 10000 --json > "backup-$ns.json"
done

---

Troubleshooting

Connection Issues

# Check if HeroDB is running
redis-cli -p 6379 PING

# Verify configuration
cat ~/.config/osiris/config.toml

Object Not Found

# List all objects in a namespace
./target/release/osiris find --ns notes --topk 1000

# Check if namespace exists
./target/release/osiris ns list

Search Returns No Results

# Try without filters first
./target/release/osiris find "keyword" --ns notes

# Check if objects have the expected tags
./target/release/osiris get notes/some-id

---

Next Steps

• Explore the README for more information
• Read the MVP Specification
• Check out the source code to understand the implementation
• Contribute improvements or report issues

Happy organizing with OSIRIS! 🎯