osiris/EXAMPLES.md

# OSIRIS Examples

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

## Prerequisites

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

2. **Build OSIRIS**:
```bash
cd /path/to/osiris
cargo build --release
```

3. **Initialize OSIRIS**:
```bash
./target/release/osiris init --herodb redis://localhost:6379
```

---

## Example 1: Personal Note Management

### Create a namespace for notes
```bash
./target/release/osiris ns create notes
```

### Add notes with tags
```bash
# 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
```bash
# 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
```bash
# 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
```bash
./target/release/osiris del notes/rust-intro
```

---

## Example 2: Calendar/Event Management

### Create a calendar namespace
```bash
./target/release/osiris ns create calendar
```

### Add events
```bash
# 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
```bash
# 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
```bash
./target/release/osiris ns create snippets
```

### Add code snippets
```bash
# 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
```bash
# 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
```bash
./target/release/osiris ns create docs
```

### Add documents
```bash
# 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
```bash
# 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
```bash
./target/release/osiris ns list
```

### Get statistics
```bash
# 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
```bash
./target/release/osiris ns delete snippets
```

---

## Example 6: Batch Operations

### Bulk import notes
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
#!/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:
```bash
# 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:
```bash
# 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:
```bash
--mime text/markdown
--mime application/json
--mime text/x-rust
--mime text/plain
```

### 4. Leverage Filters
Use filters to narrow down search results:
```bash
# 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:
```bash
# 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
```bash
# Check if HeroDB is running
redis-cli -p 6379 PING

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

### Object Not Found
```bash
# 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
```bash
# 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](README.md) for more information
- Read the [MVP Specification](docs/specs/osiris-mvp.md)
- Check out the [source code](src/) to understand the implementation
- Contribute improvements or report issues

Happy organizing with OSIRIS! 🎯