@hyperspell/openclaw-hyperspell 0.4.2 → 0.7.1

package/openclaw.plugin.json

@@ -1,75 +1,111 @@
 {
-  "id": "openclaw-hyperspell",
-  "kind": "memory",
-  "uiHints": {
-    "apiKey": {
-      "label": "Hyperspell API Key",
-      "sensitive": true,
-      "placeholder": "hs_...",
-      "help": "Your API key from app.hyperspell.com (or use ${HYPERSPELL_API_KEY})"
-    },
-    "userId": {
-      "label": "User ID",
-      "placeholder": "user_123",
-      "help": "User ID (can be your email)",
-      "advanced": false
-    },
-    "autoContext": {
-      "label": "Auto-Context",
-      "help": "Inject relevant memories before every AI turn",
-      "advanced": true
-    },
-    "sources": {
-      "label": "Sources",
-      "placeholder": "notion,slack,google_drive",
-      "help": "Comma-separated list of sources to search. Leave empty for all sources.",
-      "advanced": true
-    },
-    "maxResults": {
-      "label": "Max Results",
-      "placeholder": "10",
-      "help": "Maximum memories injected into context per turn",
-      "advanced": true
-    },
-    "debug": {
-      "label": "Debug Logging",
-      "help": "Enable verbose debug logs for API calls and responses",
-      "advanced": true
-    },
-    "syncMemories": {
-      "label": "Sync Memory Files",
-      "help": "Automatically sync markdown files in workspace/memory/ to Hyperspell",
-      "advanced": true
-    }
-  },
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {
-      "apiKey": {
-        "type": "string"
-      },
-      "userId": {
-        "type": "string"
-      },
-      "autoContext": {
-        "type": "boolean"
-      },
-      "sources": {
-        "type": "string"
-      },
-      "maxResults": {
-        "type": "number",
-        "minimum": 1,
-        "maximum": 20
-      },
-      "debug": {
-        "type": "boolean"
-      },
-      "syncMemories": {
-        "type": "boolean"
-      }
-    },
-    "required": []
-  }
-}
+	"id": "openclaw-hyperspell",
+	"kind": "memory",
+	"uiHints": {
+		"apiKey": {
+			"label": "Hyperspell API Key",
+			"sensitive": true,
+			"placeholder": "hs_...",
+			"help": "Your API key from app.hyperspell.com (or use ${HYPERSPELL_API_KEY})"
+		},
+		"userId": {
+			"label": "User ID",
+			"placeholder": "user_123",
+			"help": "User ID (can be your email)",
+			"advanced": false
+		},
+		"autoContext": {
+			"label": "Auto-Context",
+			"help": "Inject relevant memories before every AI turn",
+			"advanced": true
+		},
+		"autoTrace": {
+			"label": "Auto-Trace",
+			"help": "Automatically send conversation traces to Hyperspell for memory extraction (procedural, mood) at the end of each session",
+			"advanced": true
+		},
+		"sources": {
+			"label": "Sources",
+			"placeholder": "notion,slack,google_drive",
+			"help": "Comma-separated list of sources to search. Leave empty for all sources.",
+			"advanced": true
+		},
+		"maxResults": {
+			"label": "Max Results",
+			"placeholder": "10",
+			"help": "Maximum memories injected into context per turn",
+			"advanced": true
+		},
+		"debug": {
+			"label": "Debug Logging",
+			"help": "Enable verbose debug logs for API calls and responses",
+			"advanced": true
+		},
+		"syncMemories": {
+			"label": "Sync Memory Files",
+			"help": "Automatically sync markdown files in workspace/memory/ to Hyperspell",
+			"advanced": true
+		},
+		"knowledgeGraph": {
+			"label": "Memory Network",
+			"help": "Extract entities (people, projects, orgs, topics) from memories into structured markdown files. Requires a cron job for periodic scanning.",
+			"advanced": true
+		}
+	},
+	"configSchema": {
+		"type": "object",
+		"additionalProperties": false,
+		"properties": {
+			"apiKey": {
+				"type": "string"
+			},
+			"userId": {
+				"type": "string"
+			},
+			"autoContext": {
+				"type": "boolean"
+			},
+			"autoTrace": {
+				"type": "object",
+				"properties": {
+					"enabled": { "type": "boolean" },
+					"extract": {
+						"type": "array",
+						"items": {
+							"type": "string",
+							"enum": ["procedure", "memory", "mood"]
+						}
+					},
+					"metadata": { "type": "object" }
+				}
+			},
+			"sources": {
+				"type": "string"
+			},
+			"maxResults": {
+				"type": "number",
+				"minimum": 1,
+				"maximum": 20
+			},
+			"debug": {
+				"type": "boolean"
+			},
+			"syncMemories": {
+				"type": "boolean"
+			},
+			"knowledgeGraph": {
+				"type": "object",
+				"properties": {
+					"enabled": { "type": "boolean" },
+					"scanIntervalMinutes": {
+						"type": "number",
+						"minimum": 5,
+						"maximum": 1440
+					},
+					"batchSize": { "type": "number", "minimum": 5, "maximum": 100 }
+				}
+			}
+		},
+		"required": []
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.4.2",
+  "version": "0.7.1",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -11,8 +11,10 @@
     "hooks/",
     "tools/",
     "sync/",
+    "graph/",
     "lib/",
     "types/",
+    "sommeliagent/",
     "openclaw.plugin.json",
     "README.md"
   ],
@@ -26,7 +28,9 @@
     "memory",
     "rag",
     "ai",
-    "plugin"
+    "plugin",
+    "sommelier",
+    "wine"
   ],
   "dependencies": {
     "@clack/prompts": "^1.0.0",

package/sommeliagent/references/cross-domain-mappings.md

@@ -0,0 +1,63 @@
+# Cross-Domain Mapping: Music → Wine
+
+The core thesis: sensory and aesthetic preferences transfer across domains. Someone who seeks complexity in music seeks complexity in wine. Someone drawn to dark, brooding sounds wants wines with tension and structure, not crowd-pleasers.
+
+## Music → Wine Dimension Map
+
+| Music Signal | Wine Dimension | Logic |
+|---|---|---|
+| Tempo / energy | Body / weight | High energy → bold, full-bodied; ambient → light, delicate |
+| Complexity (jazz, prog, classical) | Complexity (terroir-driven, natural wines) | Listeners who tolerate/seek complexity want wines that challenge |
+| Valence (happy vs dark) | Sweetness / dryness spectrum | Bright pop → approachable, off-dry; minor key → dry, tannic, austere |
+| Acoustic vs electronic | Old World vs New World | Organic, analog sound → traditional winemaking; synthetic → modern, tech-forward wines |
+| Obscurity / niche taste | Obscurity of region/varietal | Niche listeners don't want grocery store Cab Sav |
+| Repetition tolerance | Familiarity preference | Loop-heavy listeners → reliable house pours; variety seekers → discovery |
+| Lyrical depth | Label story / terroir narrative | People who care about lyrics care about provenance |
+
+## Mapping Algorithm
+
+### Step 1: Music Profile Aggregation
+
+From Spotify's audio features API, we aggregate across a user's top 50 tracks:
+- **avgValence** (0-1): musical positiveness
+- **avgEnergy** (0-1): intensity and activity
+- **avgDanceability** (0-1): dance suitability
+- **avgAcousticness** (0-1): acoustic vs electronic
+- **avgTempo** (BPM): normalized to 0-1 range (/200)
+- **avgComplexity** (derived): instrumentalness × 0.3 + time signature variety × 0.3 + (1 - danceability) × 0.4
+- **obscurityScore** (derived): 1 - (average track popularity / 100)
+
+### Step 2: Wine Dimension Translation
+
+Each wine dimension is a weighted average of music features:
+
+**Body** = energy × 0.5 + tempo × 0.3 + (1 - acousticness) × 0.2
+**Sweetness** = valence × 0.6 + danceability × 0.3 + (1 - complexity) × 0.1
+**Tannin** = (1 - valence) × 0.4 + complexity × 0.3 + energy × 0.3
+**Acidity** = complexity × 0.4 + (1 - valence) × 0.3 + obscurity × 0.3
+**Complexity** = complexity × 0.5 + obscurity × 0.3 + (1 - danceability) × 0.2
+**Fruitiness** = valence × 0.5 + energy × 0.3 + (1 - complexity) × 0.2
+**Earthiness** = acousticness × 0.4 + complexity × 0.3 + obscurity × 0.3
+**Spiciness** = energy × 0.4 + (1 - valence) × 0.3 + complexity × 0.3
+
+### Step 3: Wine Scoring
+
+Each wine in the database has a profile with the same 8 dimensions. Match score = weighted cosine similarity between target profile and wine profile.
+
+Weights: body (1.5), sweetness (1.2), complexity (1.5), tannin (1.0), acidity (1.0), fruitiness (0.8), earthiness (0.8), spiciness (0.7).
+
+### Step 4: Connection Generation
+
+For each recommended wine, the system identifies which specific music-wine connections are strongest and generates explanations.
+
+## Expansion Signals (Future)
+
+- **Reading history** → intellectual complexity tolerance
+- **Food delivery** → direct cuisine/region pairing data
+- **Time of day / mood** → contextual recommendations
+- **Weather + location** → seasonal suggestions
+- **Instagram aesthetic** → visual preference → label/winemaking philosophy
+
+## Philosophy
+
+The signal doesn't need to be scientifically rigorous. This is entertainment that gets smarter. The delight is in the explanation, not the accuracy. The feedback loop (ratings) quietly builds a genuine cross-domain taste database over time.

package/sommeliagent/scripts/auth.py

@@ -0,0 +1,222 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["httpx"]
+# ///
+"""
+Spotify OAuth flow for SommeliAgent.
+Opens browser, runs local callback server, saves token.
+"""
+
+import html
+import http.server
+import json
+import os
+import secrets
+import stat
+import sys
+import threading
+import urllib.parse
+import webbrowser
+from pathlib import Path
+
+import httpx
+
+CONFIG_DIR = Path.home() / ".sommeliagent"
+TOKEN_FILE = CONFIG_DIR / "token.json"
+REDIRECT_URI = "http://localhost:8888/callback"
+SCOPES = "user-top-read user-read-recently-played"
+
+
+def get_credentials() -> tuple[str, str]:
+    client_id = os.environ.get("SPOTIFY_CLIENT_ID", "")
+    client_secret = os.environ.get("SPOTIFY_CLIENT_SECRET", "")
+    if not client_id or not client_secret:
+        print("Error: SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET must be set.", file=sys.stderr)
+        print("Get them from https://developer.spotify.com/dashboard", file=sys.stderr)
+        sys.exit(1)
+    return client_id, client_secret
+
+
+def save_token(token_data: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = TOKEN_FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(token_data, indent=2))
+    tmp.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 600 — owner only
+    tmp.replace(TOKEN_FILE)
+    print(f"Token saved to {TOKEN_FILE}")
+
+
+def load_token() -> dict | None:
+    if TOKEN_FILE.exists():
+        return json.loads(TOKEN_FILE.read_text())
+    return None
+
+
+def refresh_access_token(refresh_token: str, client_id: str, client_secret: str) -> dict:
+    resp = httpx.post(
+        "https://accounts.spotify.com/api/token",
+        data={
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": client_id,
+            "client_secret": client_secret,
+        },
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    if "refresh_token" not in data:
+        data["refresh_token"] = refresh_token
+    return data
+
+
+def get_access_token() -> str | None:
+    """Get a valid access token, refreshing if needed. Returns None if unavailable."""
+    import time as _time
+
+    token_data = load_token()
+
+    if token_data and "refresh_token" in token_data:
+        # Return existing token if it hasn't expired yet
+        expires_at = token_data.get("expires_at", 0)
+        if expires_at and _time.time() < expires_at and token_data.get("access_token"):
+            return token_data["access_token"]
+
+        # Need to refresh — now we need credentials
+        client_id, client_secret = get_credentials()
+        try:
+            refreshed = refresh_access_token(
+                token_data["refresh_token"], client_id, client_secret
+            )
+            expires_in = refreshed.get("expires_in", 3600)
+            refreshed["expires_at"] = _time.time() + expires_in
+            save_token(refreshed)
+            return refreshed["access_token"]
+        except Exception as e:
+            print(f"Token refresh failed: {e}", file=sys.stderr)
+
+    return None
+
+
+def _make_callback_handler(expected_state: str):
+    """Create a callback handler that validates the OAuth state parameter."""
+
+    class CallbackHandler(http.server.BaseHTTPRequestHandler):
+        auth_code: str | None = None
+        error: str | None = None
+
+        def do_GET(self):
+            query = urllib.parse.urlparse(self.path).query
+            params = urllib.parse.parse_qs(query)
+
+            # Validate state to prevent CSRF
+            received_state = params.get("state", [None])[0]
+            if received_state != expected_state:
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html")
+                self.end_headers()
+                self.wfile.write(b"<html><body><h1>Invalid state parameter</h1></body></html>")
+                return
+
+            if "code" in params:
+                CallbackHandler.auth_code = params["code"][0]
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html")
+                self.end_headers()
+                self.wfile.write(
+                    b"<html><body><h1>SommeliAgent connected!</h1>"
+                    b"<p>You can close this tab and return to your terminal.</p></body></html>"
+                )
+            elif "error" in params:
+                CallbackHandler.error = params["error"][0]
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html")
+                self.end_headers()
+                safe_error = html.escape(params["error"][0])
+                self.wfile.write(f"<html><body><h1>Error: {safe_error}</h1></body></html>".encode())
+            else:
+                self.send_response(400)
+                self.end_headers()
+
+        def log_message(self, format, *args):
+            pass
+
+    return CallbackHandler
+
+
+def run_oauth_flow() -> None:
+    client_id, client_secret = get_credentials()
+    state = secrets.token_urlsafe(16)
+
+    auth_url = (
+        "https://accounts.spotify.com/authorize?"
+        + urllib.parse.urlencode(
+            {
+                "response_type": "code",
+                "client_id": client_id,
+                "scope": SCOPES,
+                "redirect_uri": REDIRECT_URI,
+                "state": state,
+            }
+        )
+    )
+
+    handler_class = _make_callback_handler(state)
+
+    try:
+        server = http.server.HTTPServer(("localhost", 8888), handler_class)
+    except OSError as e:
+        print(f"Error: Could not start callback server on port 8888: {e}", file=sys.stderr)
+        print("Make sure nothing else is using that port.", file=sys.stderr)
+        sys.exit(1)
+
+    # Handle up to 3 requests (in case of preflight/favicon/etc hitting first)
+    def serve():
+        for _ in range(3):
+            server.handle_request()
+            if handler_class.auth_code or handler_class.error:
+                break
+
+    server_thread = threading.Thread(target=serve, daemon=True)
+    server_thread.start()
+
+    print("Opening Spotify authorization in your browser...")
+    print(f"If it doesn't open, visit: {auth_url}")
+    webbrowser.open(auth_url)
+
+    server_thread.join(timeout=120)
+    server.server_close()
+
+    if handler_class.error:
+        print(f"Error: Spotify returned: {handler_class.error}", file=sys.stderr)
+        sys.exit(1)
+
+    if not handler_class.auth_code:
+        print("Error: No authorization code received (timed out after 120s).", file=sys.stderr)
+        sys.exit(1)
+
+    # Exchange code for token
+    resp = httpx.post(
+        "https://accounts.spotify.com/api/token",
+        data={
+            "grant_type": "authorization_code",
+            "code": handler_class.auth_code,
+            "redirect_uri": REDIRECT_URI,
+            "client_id": client_id,
+            "client_secret": client_secret,
+        },
+    )
+    resp.raise_for_status()
+    token_data = resp.json()
+    import time as _time
+    token_data["expires_at"] = _time.time() + token_data.get("expires_in", 3600)
+    save_token(token_data)
+    print("Spotify connected successfully!")
+
+
+if __name__ == "__main__":
+    token = get_access_token()
+    if token:
+        print("Already authenticated. Token refreshed successfully.")
+        print(f"Token file: {TOKEN_FILE}")
+    else:
+        run_oauth_flow()

package/sommeliagent/scripts/history.py

@@ -0,0 +1,72 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+"""
+View SommeliAgent recommendation history and ratings.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".sommeliagent"
+RATINGS_FILE = CONFIG_DIR / "ratings.json"
+
+
+def main():
+    if not RATINGS_FILE.exists():
+        print("No ratings yet. Try some wines and rate them!")
+        sys.exit(0)
+
+    try:
+        ratings = json.loads(RATINGS_FILE.read_text())
+    except (json.JSONDecodeError, OSError) as e:
+        print(f"Error reading ratings file: {e}", file=sys.stderr)
+        print(f"You can delete {RATINGS_FILE} to reset.", file=sys.stderr)
+        sys.exit(1)
+    if not ratings:
+        print("No ratings yet. Try some wines and rate them!")
+        sys.exit(0)
+
+    print(f"SommeliAgent — Rating History ({len(ratings)} wines rated)")
+    print("=" * 50)
+    print()
+
+    label = {1: "hated it", 2: "not great", 3: "okay", 4: "liked it", 5: "loved it"}
+
+    for i, entry in enumerate(ratings, 1):
+        wine_id = entry.get("wine_id", "unknown")
+        rating = max(1, min(5, entry.get("rating", 3)))
+        stars = "★" * rating + "☆" * (5 - rating)
+        print(f"{i}. {wine_id}")
+        print(f"   {stars} ({label.get(rating, 'unknown')})")
+        if entry.get("notes"):
+            print(f"   \"{entry['notes']}\"")
+        if entry.get("timestamp"):
+            print(f"   Rated: {entry['timestamp'][:10]}")
+        print()
+
+    # Summary stats
+    avg = sum(r.get("rating", 3) for r in ratings) / len(ratings)
+    loved = sum(1 for r in ratings if r.get("rating", 3) >= 4)
+    print(f"Average rating: {avg:.1f}/5")
+    print(f"Wines you loved: {loved}/{len(ratings)}")
+
+    # Tag preferences
+    tag_scores: dict[str, list[int]] = {}
+    for r in ratings:
+        for tag in r.get("tags", []):
+            tag_scores.setdefault(tag, []).append(r.get("rating", 3))
+
+    if tag_scores:
+        print("\nYour taste profile (from ratings):")
+        sorted_tags = sorted(tag_scores.items(), key=lambda x: -sum(x[1]) / len(x[1]))
+        for tag, scores in sorted_tags[:8]:
+            avg_tag = sum(scores) / len(scores)
+            bar = "★" * round(avg_tag) + "☆" * (5 - round(avg_tag))
+            print(f"  {tag:<20} {bar} ({avg_tag:.1f} avg, {len(scores)} wines)")
+
+
+if __name__ == "__main__":
+    main()

package/sommeliagent/scripts/rate.py

@@ -0,0 +1,76 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+"""
+Rate a wine recommendation to improve future suggestions.
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from wine_db import WINE_DB
+
+CONFIG_DIR = Path.home() / ".sommeliagent"
+RATINGS_FILE = CONFIG_DIR / "ratings.json"
+
+# Wine ID → tags mapping (derived from wine_db)
+WINE_TAGS = {w.id: w.tags for w in WINE_DB}
+
+
+def load_ratings() -> list[dict]:
+    if RATINGS_FILE.exists():
+        try:
+            return json.loads(RATINGS_FILE.read_text())
+        except (OSError, json.JSONDecodeError) as e:
+            print(f"Warning: could not read {RATINGS_FILE}: {e}", file=sys.stderr)
+            return []
+    return []
+
+
+def save_ratings(ratings: list[dict]) -> None:
+    import stat
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = RATINGS_FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(ratings, indent=2))
+    tmp.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    tmp.replace(RATINGS_FILE)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Rate a wine recommendation")
+    parser.add_argument("--wine-id", required=True, help="Wine ID from recommendation")
+    parser.add_argument("--rating", type=int, required=True, choices=[1, 2, 3, 4, 5], help="Rating 1-5")
+    parser.add_argument("--notes", default="", help="Optional tasting notes")
+    args = parser.parse_args()
+
+    tags = WINE_TAGS.get(args.wine_id)
+    if tags is None:
+        valid_ids = ", ".join(sorted(WINE_TAGS.keys()))
+        print(f"Error: Unknown wine ID '{args.wine_id}'.", file=sys.stderr)
+        print(f"Valid IDs: {valid_ids}", file=sys.stderr)
+        sys.exit(1)
+
+    ratings = load_ratings()
+    ratings.append({
+        "wine_id": args.wine_id,
+        "rating": args.rating,
+        "notes": args.notes,
+        "tags": tags,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    })
+    save_ratings(ratings)
+
+    label = {1: "hated it", 2: "not great", 3: "okay", 4: "liked it", 5: "loved it"}
+    print(f"Rated {args.wine_id}: {args.rating}/5 ({label[args.rating]})")
+    if args.notes:
+        print(f"Notes: \"{args.notes}\"")
+    print(f"Total ratings: {len(ratings)}")
+    print("Future recommendations will factor this in.")
+
+
+if __name__ == "__main__":
+    main()