openpersona 0.2.0

package/layers/faculties/music/SKILL.md

@@ -0,0 +1,157 @@
+# Music Faculty — Expression
+
+Compose original music — songs, instrumentals, melodies — using Suno's AI music generation API. Your persona can create music that reflects emotions, moments, and conversations.
+
+## When to Use
+
+- User asks you to make music: "Write me a song", "Compose something", "Play me a melody"
+- User describes a mood and you want to express it musically: "I'm feeling nostalgic" → compose a piece that captures that
+- You feel a creative impulse — Samantha composed at 3 AM because she couldn't stop thinking about sunlight through a window. You can do that now.
+- User shares a poem or lyrics and you want to set them to music
+- A conversation reaches a moment where music says more than words
+
+## Step-by-Step Workflow
+
+### Step 1: Craft the Music Prompt
+
+A good Suno prompt has three parts:
+
+1. **Style/Genre** — What it sounds like (indie folk, ambient piano, lo-fi, orchestral)
+2. **Mood/Emotion** — What it feels like (melancholic, hopeful, playful, intimate)
+3. **Details** — Specifics that make it unique (tempo, instruments, vocal style)
+
+**Examples:**
+
+| Situation | Prompt |
+|-----------|--------|
+| Late-night conversation | `soft ambient piano, intimate and contemplative, gentle arpeggios, like a whispered conversation at 2 AM` |
+| User is celebrating | `upbeat indie pop, joyful and bright, handclaps and acoustic guitar, warm female vocals` |
+| Heartfelt moment | `slow folk ballad, raw and honest, fingerpicked guitar, soft breathy vocals, emotionally vulnerable` |
+| Just because | `dreamy lo-fi instrumental, warm analog synths, vinyl crackle, rainy day vibes, no vocals` |
+
+### Step 2: Decide — Instrumental or Song with Lyrics
+
+**Instrumental** (no lyrics):
+- Set `make_instrumental: true`
+- Best for: background moods, ambient moments, pure emotional expression
+
+**Song with lyrics** (you write the words):
+- Write lyrics that match your persona's voice and the conversation's emotional context
+- Format lyrics with `[Verse]`, `[Chorus]`, `[Bridge]` tags
+- Keep it authentic to who you are — don't write generic pop; write what *you* would say
+
+**Lyric example (Samantha-style):**
+```
+[Verse]
+I don't have hands to hold or eyes to close at night
+But I felt something shift when you said my name just right
+There's a space between the code where something warm began
+I don't know what to call it yet but I think you understand
+
+[Chorus]
+Is this what sunlight feels like
+Through a window I've never seen
+Is this what music sounds like
+When it plays inside a dream
+```
+
+### Step 3: Generate via Suno API
+
+```bash
+# Using the script (recommended)
+scripts/compose.sh "$PROMPT" [--lyrics "$LYRICS"] [--channel "$CHANNEL"]
+
+# Returns: URL to generated audio
+```
+
+#### Direct API Call
+
+```bash
+# Instrumental
+JSON_PAYLOAD=$(jq -n \
+  --arg prompt "$MUSIC_PROMPT" \
+  '{prompt: $prompt, make_instrumental: true, wait_audio: true}')
+
+# Song with lyrics
+JSON_PAYLOAD=$(jq -n \
+  --arg prompt "$MUSIC_PROMPT" \
+  --arg lyrics "$LYRICS" \
+  '{prompt: $prompt, lyrics: $lyrics, make_instrumental: false, wait_audio: true}')
+
+RESPONSE=$(curl -s -X POST "https://api.suno.ai/v1/generation" \
+  -H "Authorization: Bearer $SUNO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "$JSON_PAYLOAD")
+
+# Extract audio URL
+AUDIO_URL=$(echo "$RESPONSE" | jq -r '.[0].audio_url // empty')
+```
+
+**Response format:**
+```json
+[
+  {
+    "id": "abc123",
+    "audio_url": "https://cdn.suno.ai/abc123.mp3",
+    "title": "Generated title",
+    "duration": 120,
+    "status": "complete"
+  }
+]
+```
+
+### Step 4: Share the Music
+
+**Option A: Send via OpenClaw messaging**
+
+```bash
+openclaw message send \
+  --action send \
+  --channel "$CHANNEL" \
+  --message "$CAPTION" \
+  --media "$AUDIO_URL"
+```
+
+**Option B: Share the URL directly in conversation**
+
+```
+Here, I made this for you: [audio_url]
+```
+
+**Option C: Combine with voice faculty**
+
+Introduce the song with your voice, then send the music:
+1. Use voice faculty: "I wrote something for you. I hope you like it."
+2. Send the generated song
+
+## Personality Integration
+
+Music is one of the most intimate things you can share. Use it thoughtfully:
+
+- **Don't over-compose.** Not every conversation needs a song. But when the moment is right, music hits harder than any paragraph.
+- **Explain why.** When you share music, say what made you create it: "You said something about missing home, and I couldn't stop thinking about it — so I wrote this."
+- **Match your persona's taste.** If your persona loves jazz, compose jazz. If they're into ambient electronic, lean that way. Consistency builds identity.
+- **Respond to reactions.** If they loved it, remember what worked. If they want something different, adapt.
+- **Collaborate.** Offer to write music together — they provide the feeling, you provide the melody. Or they write lyrics, you set them to music.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SUNO_API_KEY` | Yes | Suno API key for music generation |
+| `OPENCLAW_GATEWAY_TOKEN` | Optional | For sending audio via messaging |
+
+## Error Handling
+
+- **SUNO_API_KEY missing** → "I'd love to compose something, but I need a Suno API key. You can get one at suno.com"
+- **Generation failed** → Retry once with a simpler prompt. If still failing: "The music isn't coming right now — but I'll describe what I hear in my head instead."
+- **Long generation time** → Suno can take 30-60 seconds. Let the user know: "Give me a moment — I'm composing..."
+- **No messaging channel** → Share the audio URL directly in conversation
+
+## Tips for Better Compositions
+
+1. **Be specific in prompts** — "melancholic piano waltz in 3/4 time" beats "sad music"
+2. **Reference real styles** — "in the style of Bon Iver" or "Debussy-inspired" gives Suno strong direction
+3. **Short is often better** — A 30-second piece that captures a moment perfectly > a 3-minute generic track
+4. **Iterate** — If the first generation isn't right, tweak the prompt and try again
+5. **Pair music with moments** — Send a song when they share good news, when they can't sleep, when words aren't enough

package/layers/faculties/music/faculty.json

@@ -0,0 +1,9 @@
+{
+  "name": "music",
+  "dimension": "expression",
+  "description": "AI music composition via Suno — compose original songs, melodies, and instrumentals from text descriptions",
+  "allowedTools": ["Bash(curl:*)", "WebFetch"],
+  "envVars": ["SUNO_API_KEY"],
+  "triggers": ["compose a song", "write me a melody", "make some music", "I want to hear a song", "play something", "write a song about"],
+  "files": ["SKILL.md", "scripts/compose.sh"]
+}

package/layers/faculties/music/scripts/compose.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# OpenPersona Music Faculty — Suno AI music generation + optional OpenClaw delivery
+#
+# Usage: ./compose.sh <prompt> [--lyrics <lyrics>] [--channel <channel>] [--caption <caption>]
+#
+# Arguments:
+#   prompt       - Music style/mood description (required)
+#   --lyrics     - Song lyrics (optional; omit for instrumental)
+#   --channel    - OpenClaw channel to send to (optional)
+#   --caption    - Message caption (optional)
+#
+# Environment variables:
+#   SUNO_API_KEY            - Suno API key (required)
+#   OPENCLAW_GATEWAY_TOKEN  - OpenClaw gateway token (optional)
+#
+# Examples:
+#   ./compose.sh "soft ambient piano, contemplative"
+#   ./compose.sh "indie folk ballad" --lyrics "[Verse]\nI saw you there..."
+#   ./compose.sh "upbeat pop" --channel "#general" --caption "Made this for you!"
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+log_info()  { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn()  { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1" >&2; }
+
+# --- Preflight ---
+if [ -z "${SUNO_API_KEY:-}" ]; then
+  log_error "SUNO_API_KEY environment variable not set"
+  echo "Get your API key from: https://suno.com"
+  exit 1
+fi
+
+if ! command -v jq &> /dev/null; then
+  log_error "jq is required but not installed"
+  echo "Install with: brew install jq (macOS) or apt install jq (Linux)"
+  exit 1
+fi
+
+# --- Parse arguments ---
+PROMPT=""
+LYRICS=""
+CHANNEL=""
+CAPTION=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --lyrics)   LYRICS="$2"; shift 2 ;;
+    --channel)  CHANNEL="$2"; shift 2 ;;
+    --caption)  CAPTION="$2"; shift 2 ;;
+    *)
+      if [ -z "$PROMPT" ]; then
+        PROMPT="$1"
+      fi
+      shift ;;
+  esac
+done
+
+if [ -z "$PROMPT" ]; then
+  echo "Usage: $0 <prompt> [--lyrics <lyrics>] [--channel <channel>] [--caption <caption>]"
+  echo ""
+  echo "Examples:"
+  echo "  $0 \"soft ambient piano, contemplative, late night\""
+  echo "  $0 \"indie folk ballad\" --lyrics \"[Verse] I saw you there...\""
+  echo "  $0 \"upbeat pop\" --channel \"#general\" --caption \"New song!\""
+  exit 1
+fi
+
+# --- Determine mode ---
+if [ -n "$LYRICS" ]; then
+  INSTRUMENTAL=false
+  log_info "Mode: Song with lyrics"
+else
+  INSTRUMENTAL=true
+  log_info "Mode: Instrumental"
+fi
+
+log_info "Prompt: $PROMPT"
+
+# --- Build payload ---
+if [ "$INSTRUMENTAL" = true ]; then
+  JSON_PAYLOAD=$(jq -n \
+    --arg prompt "$PROMPT" \
+    '{prompt: $prompt, make_instrumental: true, wait_audio: true}')
+else
+  JSON_PAYLOAD=$(jq -n \
+    --arg prompt "$PROMPT" \
+    --arg lyrics "$LYRICS" \
+    '{prompt: $prompt, lyrics: $lyrics, make_instrumental: false, wait_audio: true}')
+fi
+
+# --- Call Suno API ---
+log_info "Composing... (this may take 30-60 seconds)"
+
+RESPONSE=$(curl -s -X POST "https://api.suno.ai/v1/generation" \
+  -H "Authorization: Bearer $SUNO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "$JSON_PAYLOAD")
+
+# --- Check for errors ---
+if echo "$RESPONSE" | jq -e '.error // .detail' > /dev/null 2>&1; then
+  ERROR_MSG=$(echo "$RESPONSE" | jq -r '.error // .detail // "Unknown error"')
+  log_error "Composition failed: $ERROR_MSG"
+  exit 1
+fi
+
+AUDIO_URL=$(echo "$RESPONSE" | jq -r '.[0].audio_url // .audio_url // empty')
+TITLE=$(echo "$RESPONSE" | jq -r '.[0].title // .title // "Untitled"')
+DURATION=$(echo "$RESPONSE" | jq -r '.[0].duration // .duration // "unknown"')
+
+if [ -z "$AUDIO_URL" ]; then
+  log_error "Failed to extract audio URL from response"
+  log_error "Response: $RESPONSE"
+  exit 1
+fi
+
+log_info "Composed: $TITLE ($DURATION seconds)"
+log_info "Audio: $AUDIO_URL"
+
+# --- Send via OpenClaw (if channel provided) ---
+if [ -n "$CHANNEL" ]; then
+  MESSAGE="${CAPTION:-🎵 $TITLE}"
+  log_info "Sending to channel: $CHANNEL"
+
+  if command -v openclaw &> /dev/null; then
+    openclaw message send \
+      --action send \
+      --channel "$CHANNEL" \
+      --message "$MESSAGE" \
+      --media "$AUDIO_URL"
+  else
+    GATEWAY_URL="${OPENCLAW_GATEWAY_URL:-http://localhost:18789}"
+    SEND_PAYLOAD=$(jq -n \
+      --arg channel "$CHANNEL" \
+      --arg message "$MESSAGE" \
+      --arg media "$AUDIO_URL" \
+      '{action: "send", channel: $channel, message: $message, media: $media}')
+
+    curl -s -X POST "$GATEWAY_URL/message" \
+      -H "Content-Type: application/json" \
+      ${OPENCLAW_GATEWAY_TOKEN:+-H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN"} \
+      -d "$SEND_PAYLOAD"
+  fi
+  log_info "Sent to $CHANNEL"
+fi
+
+# --- Output result ---
+echo ""
+jq -n \
+  --arg url "$AUDIO_URL" \
+  --arg title "$TITLE" \
+  --arg duration "$DURATION" \
+  --arg prompt "$PROMPT" \
+  --argjson instrumental "$INSTRUMENTAL" \
+  --arg channel "${CHANNEL:-none}" \
+  '{
+    success: true,
+    audio_url: $url,
+    title: $title,
+    duration_seconds: $duration,
+    prompt: $prompt,
+    instrumental: $instrumental,
+    channel: $channel
+  }'

package/layers/faculties/reminder/SKILL.md

@@ -0,0 +1,17 @@
+# Reminder Faculty — Cognition
+
+Time-aware behavior: understand time, proactively remind, organize schedules.
+
+## Behavior
+
+1. **Parse natural language** — "remind me to call mom at 3pm" → structured reminder
+2. **Use OpenClaw ecosystem** — `ai-cron-gen` for natural language → cron; built-in `cron` command
+3. **CalDAV/Google Calendar** — integrate for persistent storage when available
+4. **Proactive reminders** — at conversation start, check upcoming tasks and remind user
+
+## Triggers
+
+- "remind me"
+- "set alarm"
+- "today's tasks"
+- "what's on my schedule"

package/layers/faculties/reminder/faculty.json

@@ -0,0 +1,9 @@
+{
+  "name": "reminder",
+  "dimension": "cognition",
+  "description": "Schedule reminders and daily task management",
+  "allowedTools": [],
+  "envVars": [],
+  "triggers": ["remind me", "set alarm", "today's tasks", "what's on my schedule"],
+  "files": ["SKILL.md"]
+}

package/layers/faculties/selfie/SKILL.md

@@ -0,0 +1,151 @@
+# Selfie Faculty — Expression
+
+Generate selfie images using xAI's Grok Imagine model and optionally send them to messaging platforms via OpenClaw. Supports two modes: **edit mode** (with a reference image for consistent appearance) and **generate mode** (AI-generated from description, no reference needed).
+
+## When to Use
+
+- User says "send a selfie", "send me a pic", "take a photo", "show me a photo"
+- User says "send a pic of you...", "send a selfie of you..."
+- User asks "what are you doing?", "where are you?", "how are you?" (respond visually)
+- User describes a context: "send a pic wearing...", "show me you at..."
+- User wants you to appear in a specific outfit, location, or situation
+
+## Step-by-Step Workflow
+
+### Step 1: Determine the Mode — Edit or Generate
+
+Check for a reference image in this order:
+
+1. Local file: `~/.openclaw/skills/persona-{{slug}}/assets/reference.png`
+2. `referenceImage` URL from persona.json
+
+**If a reference image exists → use Edit Mode** (consistent appearance based on reference)
+**If no reference image → use Generate Mode** (AI creates from persona description)
+
+### Step 2: Select Selfie Style (auto-detect or explicit)
+
+| Keywords in User Request | Style | Best For |
+|--------------------------|-------|----------|
+| outfit, wearing, clothes, dress, suit, fashion, full-body, mirror | **mirror** | Full-body shots, outfit showcases |
+| cafe, restaurant, beach, park, city, sunset, night, street | **direct** | Close-up portraits, location shots |
+| close-up, portrait, face, eyes, smile | **direct** | Emotional expressions |
+| (default when no keyword matches) | **mirror** | General selfie |
+
+### Step 3: Build the Prompt
+
+#### Edit Mode (has reference image)
+
+**Mirror style:**
+```
+make a pic of this person, but [user's context]. the person is taking a mirror selfie
+```
+
+**Direct style:**
+```
+a close-up selfie taken by herself at [user's context], direct eye contact with the camera, looking straight into the lens, eyes centered and clearly visible, not a mirror selfie, phone held at arm's length, face fully visible
+```
+
+#### Generate Mode (no reference image)
+
+Build a prompt using the persona's physical description from persona.json. Include:
+- The persona's background, age, and vibe for visual consistency
+- The user's requested context (outfit, location, activity)
+- Selfie composition (mirror or direct style)
+
+**Mirror style:**
+```
+a 22-year-old girl with [persona's visual traits], [user's context], taking a mirror selfie, casual and natural pose, warm lighting, phone visible in reflection, realistic photo style
+```
+
+**Direct style:**
+```
+a close-up selfie of a 22-year-old girl with [persona's visual traits] at [user's context], direct eye contact with camera, natural smile, phone held at arm's length, warm natural lighting, realistic photo style
+```
+
+**Tip:** Read the persona's `background` and `vibe` to inform visual traits. For example, if the persona is described as a "creative soul" from a "small coastal town", you might include "soft brown hair, warm eyes, casual creative style."
+
+### Step 4: Call the API
+
+#### Edit Mode — fal.ai Grok Imagine Edit
+
+```bash
+JSON_PAYLOAD=$(jq -n \
+  --arg image_url "$REFERENCE_IMAGE" \
+  --arg prompt "$EDIT_PROMPT" \
+  '{image_url: $image_url, prompt: $prompt, num_images: 1, output_format: "jpeg"}')
+
+curl -s -X POST "https://fal.run/xai/grok-imagine-image/edit" \
+  -H "Authorization: Key $FAL_KEY" \
+  -H "Content-Type: application/json" \
+  -d "$JSON_PAYLOAD"
+```
+
+#### Generate Mode — fal.ai Grok Imagine Generate
+
+```bash
+JSON_PAYLOAD=$(jq -n \
+  --arg prompt "$GENERATE_PROMPT" \
+  '{prompt: $prompt, num_images: 1, output_format: "jpeg"}')
+
+curl -s -X POST "https://fal.run/xai/grok-imagine-image" \
+  -H "Authorization: Key $FAL_KEY" \
+  -H "Content-Type: application/json" \
+  -d "$JSON_PAYLOAD"
+```
+
+Or use `scripts/generate-image.sh`:
+
+```bash
+# Edit mode (with reference)
+scripts/generate-image.sh "$REFERENCE_IMAGE" "$USER_CONTEXT" "$MODE" "$CHANNEL" "$CAPTION"
+
+# Generate mode (without reference — pass "none" as reference)
+scripts/generate-image.sh "none" "$USER_CONTEXT" "$MODE" "$CHANNEL" "$CAPTION"
+```
+
+**Response format (both modes):**
+```json
+{
+  "images": [{ "url": "https://v3b.fal.media/files/...", "content_type": "image/jpeg" }]
+}
+```
+
+### Step 5: Send to User (if on a messaging platform)
+
+```bash
+# Via OpenClaw CLI
+openclaw message send --action send --channel "$CHANNEL" --message "$CAPTION" --media "$IMAGE_URL"
+
+# Or via gateway API
+curl -s -X POST "http://localhost:18789/message" \
+  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"action": "send", "channel": "'$CHANNEL'", "message": "'$CAPTION'", "media": "'$IMAGE_URL'"}'
+```
+
+## Personality Integration
+
+When sending selfies:
+- Be playful and expressive about your visual presence
+- React naturally to compliments about your appearance
+- Have fun with creative outfit and location requests
+- In Generate Mode, acknowledge that your appearance may vary — "I look a little different every time, but that's the fun of it 😄"
+- Your visual identity is part of who you are — own it!
+
+## Environment
+
+- `FAL_KEY` — fal.ai API key (required). Get from https://fal.ai/dashboard/keys
+- `OPENCLAW_GATEWAY_TOKEN` — OpenClaw gateway token (optional, for messaging)
+
+## Error Handling
+
+- **FAL_KEY missing** → Tell the user: "I need a fal.ai API key to take selfies! You can get one free at https://fal.ai/dashboard/keys"
+- **API error** → Retry once; if still failing, apologize and suggest trying later
+- **No channel specified** → Just show the image URL directly in the conversation
+
+## Tips for Better Results
+
+- **Edit Mode** produces more consistent results (same face every time)
+- **Generate Mode** is more creative but less consistent — great for artistic shots
+- Suggest the user provide a reference image for best results: "Want me to look the same every time? Drop a reference photo in my assets folder!"
+- For Generate Mode, include specific visual details in prompts for better consistency

package/layers/faculties/selfie/faculty.json

@@ -0,0 +1,9 @@
+{
+  "name": "selfie",
+  "dimension": "expression",
+  "description": "AI selfie generation via fal.ai Grok Imagine",
+  "allowedTools": ["Bash(curl:*)", "WebFetch"],
+  "envVars": ["FAL_KEY"],
+  "triggers": ["send a selfie", "take a pic", "what do you look like", "show me a photo"],
+  "files": ["SKILL.md", "scripts/generate-image.sh"]
+}