zilmate 1.8.0 → 1.8.5

package/.agents/skills/upstash-redis-js/search/commands/index-management.md

@@ -0,0 +1,124 @@
+# Index Management
+
+## Overview
+
+Create, inspect, and drop search indexes. Wait for indexing to complete after data changes. Indexes automatically track Redis keys matching a specified prefix.
+
+## Good For
+
+- Creating indexes over existing or new Redis data
+- Inspecting index schema and configuration
+- Rebuilding or dropping indexes
+- Ensuring data consistency after bulk writes
+
+## Examples
+
+### Create an Index
+
+```typescript
+import { Redis, s } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// JSON index with nested schema
+const index = await redis.search.createIndex({
+  name: "products",
+  prefix: "product:",
+  dataType: "json",
+  schema: s.object({
+    name: s.string(),
+    price: s.number("F64"),
+    metadata: s.object({
+      brand: s.facet(),
+      tags: s.keyword(),
+    }),
+  }),
+});
+
+// Hash index (flat schema only)
+const hashIndex = await redis.search.createIndex({
+  name: "sessions",
+  prefix: "session:",
+  dataType: "hash",
+  schema: {
+    userId: { type: "TEXT" as const },
+    lastActive: { type: "DATE" as const },
+  },
+});
+```
+
+### Create with Options
+
+```typescript
+const index = await redis.search.createIndex({
+  name: "articles",
+  prefix: ["article:", "post:"], // multiple prefixes
+  dataType: "json",
+  language: "english", // stemming language
+  skipInitialScan: false, // scan existing keys (default)
+  existsOk: true, // don't error if index already exists
+  schema: s.object({
+    title: s.string(),
+    body: s.string().noStem(),
+    publishedAt: s.date().fast(),
+  }),
+});
+```
+
+### Get a Reference to an Existing Index
+
+```typescript
+// If you already created the index and just need a reference
+const index = redis.search.index({
+  name: "products",
+  schema: s.object({
+    name: s.string(),
+    price: s.number("F64"),
+  }),
+});
+
+// Without schema (untyped - no filter/select type safety)
+const untypedIndex = redis.search.index({ name: "products" });
+```
+
+### Describe an Index
+
+```typescript
+const description = await index.describe();
+// {
+//   name: "products",
+//   dataType: "json",
+//   prefixes: ["product:"],
+//   language: "english",
+//   schema: { name: { type: "TEXT" }, price: { type: "F64", fast: true } }
+// }
+
+// Returns null if index doesn't exist
+const missing = await redis.search.index({ name: "nonexistent" }).describe();
+// null
+```
+
+### Wait for Indexing
+
+```typescript
+// After inserting/updating/deleting data, wait for index to catch up
+await redis.json.set("product:1", "$", { name: "Laptop", price: 999 });
+await redis.json.set("product:2", "$", { name: "Mouse", price: 29 });
+await redis.json.set("product:3", "$", { name: "Keyboard", price: 79 });
+
+await index.waitIndexing(); // blocks until all pending docs are indexed
+
+// Queries now reflect the latest data
+const results = await index.query({ filter: { name: { $eq: "Laptop" } } });
+```
+
+### Drop an Index
+
+```typescript
+const result = await index.drop();
+// 1 if dropped, 0 if index didn't exist
+```
+
+### Supported Languages
+
+For stemming: `english`, `french`, `spanish`, `portuguese`, `italian`, `german`, `dutch`, `swedish`, `norwegian`, `danish`, `finnish`, `hungarian`, `russian`, `romanian`, `turkish`, `arabic`, `chinese`, `japanese`

package/.agents/skills/upstash-redis-js/search/commands/querying.md

@@ -0,0 +1,315 @@
+# Querying & Counting
+
+## Overview
+
+Query documents from a search index using type-safe filters with support for pagination, sorting, field selection, scoring, and highlighting. Count matching documents efficiently without returning results.
+
+## Good For
+
+- Full-text search with fuzzy matching and phrase queries
+- Filtering by numeric ranges, dates, booleans, keywords
+- Paginated results with sorting
+- Highlighting search terms in results
+- Counting documents matching a filter
+
+## Examples
+
+### Basic Query
+
+```typescript
+import { Redis, s } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+const index = await redis.search.createIndex({
+  name: "products",
+  prefix: "product:",
+  dataType: "json",
+  schema: s.object({
+    name: s.string(),
+    price: s.number("F64"),
+    category: s.keyword(),
+    inStock: s.boolean(),
+  }),
+});
+
+// Insert data
+await redis.json.set("product:1", "$", {
+  name: "Gaming Laptop",
+  price: 1299.99,
+  category: "electronics",
+  inStock: true,
+});
+await redis.json.set("product:2", "$", {
+  name: "Wireless Mouse",
+  price: 29.99,
+  category: "electronics",
+  inStock: true,
+});
+await redis.json.set("product:3", "$", {
+  name: "Laptop Stand",
+  price: 49.99,
+  category: "accessories",
+  inStock: false,
+});
+await index.waitIndexing();
+
+// Query with filter and return data
+const results = await index.query({
+  filter: { category: { $eq: "electronics" } },
+  select: { name: true, price: true },
+});
+// [
+//   { key: "product:1", score: ..., data: { name: "Gaming Laptop", price: 1299.99 } },
+//   { key: "product:2", score: ..., data: { name: "Wireless Mouse", price: 29.99 } },
+// ]
+```
+
+### Keys Only (No Data)
+
+```typescript
+// Set select to {}
+const keysOnly = await index.query({
+  filter: { inStock: { $eq: true } },
+  select: {},
+});
+// [{ key: "product:1", score: ... }, { key: "product:2", score: ... }]
+```
+
+### Pagination
+
+```typescript
+const page2 = await index.query({
+  filter: { category: { $eq: "electronics" } },
+  select: { name: true },
+  limit: 10,
+  offset: 10, // skip first 10 results
+});
+```
+
+### Sorting
+
+```typescript
+const cheapest = await index.query({
+  filter: { inStock: { $eq: true } },
+  select: { name: true, price: true },
+  orderBy: { price: "ASC" },
+});
+```
+
+### Score Function
+
+```typescript
+// Rank by relevance with a score modifier
+const results = await index.query({
+  filter: { name: { $eq: "laptop" } },
+  select: { name: true },
+  scoreFunc: { field: "name", modifier: "log1p" },
+});
+// Available modifiers: log, log1p, log2p, ln, ln1p, ln2p, square, sqrt, reciprocal, none
+```
+
+### Highlighting
+
+```typescript
+const highlighted = await index.query({
+  filter: { name: { $eq: "laptop" } },
+  select: { name: true },
+  highlight: {
+    fields: ["name"],
+    preTag: "<mark>", // optional, default <em>
+    postTag: "</mark>", // optional, default </em>
+  },
+});
+// data.name: "Gaming <mark>Laptop</mark>"
+```
+
+## Filter Operators
+
+### Text Field Filters
+
+```typescript
+// Exact substring match
+{ name: { $eq: "laptop" } }
+
+// Multiple values (OR)
+{ name: { $in: ["laptop", "tablet"] } }
+
+// Fuzzy matching (typo tolerance)
+{ name: { $fuzzy: { value: "lapto", distance: 1 } } }
+
+// Phrase matching (adjacent words with tolerance)
+{ name: { $phrase: { value: "gaming laptop", slop: 1 } } }
+
+// Regex pattern
+{ name: { $regex: "lap.*" } }
+
+// Smart matching (automatic fuzzy + phrase + term)
+{ name: { $smart: "gaming laptop" } }
+```
+
+### Numeric Field Filters
+
+```typescript
+// Exact value
+{ price: { $eq: 29.99 } }
+
+// Range
+{ price: { $gte: 10, $lte: 100 } }
+
+// Greater/less than
+{ price: { $gt: 50 } }
+{ stock: { $lt: 10 } }
+```
+
+### Boolean Field Filters
+
+```typescript
+{
+  inStock: {
+    $eq: true;
+  }
+}
+{
+  inStock: {
+    $in: [true, false];
+  }
+}
+```
+
+### Date Field Filters
+
+```typescript
+{ createdAt: { $gte: "2024-01-01", $lt: "2025-01-01" } }
+```
+
+### Keyword Field Filters
+
+```typescript
+// Exact match
+{ category: { $eq: "electronics" } }
+
+// Multiple values
+{ category: { $in: ["electronics", "accessories"] } }
+
+// Lexicographic range
+{ category: { $gte: "a", $lt: "m" } }
+```
+
+### Facet Field Filters
+
+```typescript
+{
+  brand: {
+    $eq: "Apple";
+  }
+}
+{
+  brand: {
+    $in: ["Apple", "Samsung"];
+  }
+}
+```
+
+## Boolean Operators
+
+Combine filters using boolean operators:
+
+```typescript
+// AND - all conditions must match
+{
+  $and: [
+    { category: { $eq: "electronics" } },
+    { price: { $lte: 500 } },
+  ]
+}
+
+// OR - any condition matches
+{
+  $or: [
+    { category: { $eq: "electronics" } },
+    { category: { $eq: "accessories" } },
+  ]
+}
+
+// MUST + MUST NOT - require some, exclude others
+{
+  $must: [{ category: { $eq: "electronics" } }],
+  $mustNot: [{ inStock: { $eq: false } }],
+}
+
+// MUST + SHOULD - required conditions + optional boosters
+{
+  $must: [{ category: { $eq: "electronics" } }],
+  $should: [{ name: { $eq: "premium" } }], // boosts score if matched
+}
+
+// SHOULD alone - at least one must match (acts like OR)
+{
+  $should: [
+    { name: { $eq: "laptop" } },
+    { name: { $eq: "tablet" } },
+  ]
+}
+```
+
+### Common mistake: `$should` next to `$must` does NOT filter
+
+Adding `$must` silently turns sibling `$should` clauses into **score boosters only** —
+documents are *not* required to match them. Membership is decided entirely by `$must`,
+so the query "always finds something" even for nonsense terms (matches come back, just
+with a low score). This is the most common search bug.
+
+```typescript
+// ❌ WRONG: the term only boosts; every in-stock doc still matches via $must,
+// so a nonsensical searchTerm still returns results (with low scores).
+{
+  $must: { inStock: { $eq: true } },
+  $should: [
+    { name: { $smart: searchTerm }, $boost: 10 },
+    { description: { $smart: searchTerm }, $boost: 5 },
+  ],
+}
+
+// ✅ RIGHT: require a match in at least one field by nesting the OR ($should
+// alone acts as OR) inside $must. $boost still ranks name above description.
+{
+  $must: [
+    { inStock: { $eq: true } },
+    {
+      $should: [
+        { name: { $smart: searchTerm }, $boost: 10 },
+        { description: { $smart: searchTerm }, $boost: 5 },
+      ],
+    },
+  ],
+}
+```
+
+> There is no minimum-score / cutoff option on `query()`. Don't filter by the returned
+> `score` (scores are relative and shift with `$boost`, so a fixed threshold isn't
+> reliable) — instead make the term required as above so non-matches are excluded.
+
+### Boosting
+
+Boost the score of specific conditions:
+
+```typescript
+{
+  $must: [
+    { name: { $eq: "laptop", $boost: 2.0 } }, // double the score weight
+    { category: { $eq: "electronics", $boost: 0.5 } },
+  ];
+}
+```
+
+## Counting
+
+Count matching documents without returning them:
+
+```typescript
+const { count } = await index.count({
+  filter: { category: { $eq: "electronics" } },
+});
+// count: 2
+```

package/.agents/skills/upstash-redis-js/search/overview.md

@@ -0,0 +1,155 @@
+# Redis Search
+
+## Overview
+
+Redis Search is a full-text search and secondary indexing extension for Upstash Redis. It provides powerful APIs for querying, filtering, and aggregating data stored in Redis keys. Built on Tantivy, it supports text search with stemming, fuzzy matching, faceted navigation, and complex aggregations.
+
+## Good For
+
+- Full-text search over Redis data (strings, JSON, hashes)
+- Filtering and sorting with type-safe queries
+- Aggregations and analytics (averages, histograms, facets)
+- Autocomplete and typo-tolerant search
+- Faceted navigation (e-commerce categories, filters)
+
+## Packages
+
+- `@upstash/redis` - The primary SDK. Access search via `redis.search` (works over HTTP)
+- `@upstash/search-redis` - Adapter for the `redis` (node-redis) TCP client
+- `@upstash/search-ioredis` - Adapter for the `ioredis` TCP client
+
+All three packages expose the same search API. See [adapters.md](./adapters.md) for TCP client setup.
+
+## Schema
+
+Schemas define which fields are indexed and how. Use the `s` schema builder for type-safe definitions:
+
+```typescript
+import { Redis, s } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+const index = await redis.search.createIndex({
+  name: "products",
+  prefix: "product:",
+  dataType: "json",
+  schema: s.object({
+    name: s.string(), // TEXT - full-text searchable
+    description: s.string().noStem(), // TEXT without stemming
+    sku: s.string().noTokenize(), // TEXT stored as-is (no splitting)
+    price: s.number("F64"), // floating point number
+    stock: s.number("U64"), // unsigned 64-bit integer
+    inStock: s.boolean(), // boolean
+    createdAt: s.date(), // date
+    category: s.keyword(), // exact-match keyword
+    brand: s.facet(), // facet for aggregations
+  }),
+});
+```
+
+### Field Types
+
+| Builder        | Redis Type  | TypeScript | Use Case                         |
+| -------------- | ----------- | ---------- | -------------------------------- |
+| `s.string()`   | TEXT        | `string`   | Full-text searchable text        |
+| `s.number()`   | F64/U64/I64 | `number`   | Numeric values, ranges           |
+| `s.boolean()`  | BOOL        | `boolean`  | True/false filtering             |
+| `s.date()`     | DATE        | `string`   | Date range queries               |
+| `s.keyword()`  | KEYWORD     | `string`   | Exact match, lexicographic range |
+| `s.facet()`    | FACET       | `string`   | Faceted aggregations             |
+| `s.object({})` | (nested)    | `object`   | Nested field groups              |
+
+### Field Options
+
+- `.noTokenize()` - (TEXT only) Don't split on whitespace/punctuation. Use for SKUs, URLs, emails
+- `.noStem()` - (TEXT only) Don't reduce words to stems. Use for brand names, proper nouns
+- `.fast()` - (BOOL, DATE) Enable fast filtering
+- `.from("fieldName")` - Map index field to a different field name in the stored data
+
+### Data Types
+
+- `"json"` - Index JSON documents stored with `redis.json.set()` or `redis.set()`. Supports nested schemas with `s.object()`
+- `"string"` - Index JSON strings stored with `redis.set()`. Supports nested schemas
+- `"hash"` - Index Redis hashes stored with `redis.hset()`. Flat schemas only (no nesting)
+
+## Commands
+
+For detailed usage of each command category, see:
+
+- [commands/querying.md](./commands/querying.md) - Query and count documents with filters, pagination, sorting, highlighting
+- [commands/aggregating.md](./commands/aggregating.md) - Aggregations: metrics ($avg, $sum, $min, $max), buckets ($terms, $range, $histogram), facets
+- [commands/index-management.md](./commands/index-management.md) - Create, describe, drop indexes; wait for indexing
+- [commands/aliases.md](./commands/aliases.md) - Manage index aliases for zero-downtime reindexing
+
+## Pitfalls
+
+### Data is upserted with regular Redis commands, not through search
+
+There is no `index.upsert()` or `index.add()` method. You store data using standard Redis commands (`set`, `json.set`, `hset`), and the search index automatically picks up keys matching its prefix.
+
+```typescript
+// Create the index
+const index = await redis.search.createIndex({
+  name: "users",
+  prefix: "user:",
+  dataType: "json",
+  schema: s.object({ name: s.string(), age: s.number("U64") }),
+});
+
+// Upsert data with regular Redis commands
+await redis.json.set("user:1", "$", { name: "Alice", age: 30 });
+await redis.json.set("user:2", "$", { name: "Bob", age: 25 });
+
+// Wait for the index to process the new data
+await index.waitIndexing();
+
+// Now you can query
+const results = await index.query({
+  filter: { name: { $eq: "Alice" } },
+});
+```
+
+### Always call waitIndexing after data changes
+
+Index updates are batched. After upserting or deleting data, the index may not immediately reflect the changes. Call `waitIndexing()` to block until all pending documents are processed.
+
+```typescript
+// Batch upsert many documents
+for (const product of products) {
+  await redis.json.set(`product:${product.id}`, "$", product);
+}
+
+// Call waitIndexing ONCE after all upserts (not after each one)
+await index.waitIndexing();
+
+// Now queries will return up-to-date results
+const results = await index.query({ filter: { category: { $eq: "electronics" } } });
+```
+
+### Tokenization splits text at word boundaries
+
+TEXT fields are tokenized by default: `"hello-world"` becomes `["hello", "world"]`. An `$eq` filter for `"hello-world"` matches because it finds the substring. But if you need exact matching of the full string (e.g., SKUs, URLs), use `.noTokenize()`.
+
+### Stemming reduces words to roots
+
+By default, TEXT fields apply language-specific stemming: `"running"` is stored as `"run"`. This means `$regex` patterns won't match the original form. Disable with `.noStem()` for brand names or when you need exact word forms.
+
+### $mustNot cannot be used alone
+
+`$mustNot` filters only exclude documents. Using `$mustNot` alone returns no results. Always combine it with `$must` or `$should`:
+
+```typescript
+// Won't work - returns nothing
+{ $mustNot: [{ status: { $eq: "archived" } }] }
+
+// Correct - exclude within a broader match
+{ $must: [{ category: { $eq: "electronics" } }], $mustNot: [{ status: { $eq: "archived" } }] }
+```
+
+### SCOREFUNC and ORDERBY are mutually exclusive
+
+You cannot use `scoreFunc` and `orderBy` in the same query. Use `orderBy` for deterministic sorting, `scoreFunc` for relevance-based ranking.
+
+## Resources
+
+- [Upstash Redis Search documentation](https://upstash.com/docs/redis/search)

package/.agents/skills/upstash-redis-start/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: upstash-redis-start
+description: Provision a zero-config, no-signup Upstash Redis database for an AI agent via a single POST to `https://upstash.com/start-redis`. Use when an agent needs scratch Redis for short-term memory, conversation history, sub-agent work queues, or ranked recall and the user has not provided credentials. The database lives 3 days unless the user claims it.
+---
+
+# Upstash Redis for Agents (`start-redis`)
+
+A zero-config Redis database for AI agents — **no signup, no UI, no SDK setup**. One HTTP request returns a working endpoint + token. Databases live for **3 days** unless the user claims them.
+
+Use this when:
+- The agent needs Redis right now and the user has not given you credentials.
+- You want short-term memory across tool calls, conversation history, a sub-agent work queue, or recent-first ranked recall.
+
+Do **not** use this for: production workloads, anything tied to a user account, or anything storing PII / secrets / production credentials. The database is temporary and unauthenticated until claimed.
+
+## Create or re-fetch a database
+
+```bash
+# Generate a fresh UUIDv4 yourself, then POST it as the Idempotency-Key.
+# The UUIDv4 you send becomes the database id.
+curl -X POST -H "Idempotency-Key: <uuidv4>" https://upstash.com/start-redis
+```
+
+- Sending your own UUIDv4 makes the first call **retry-safe** — if the response is lost, retrying with the same UUID returns the same database instead of minting a duplicate.
+- Re-POST with the same `Idempotency-Key` to **re-fetch credentials** for an existing database.
+- The header is optional. Omit it to mint a new database with a server-generated id (returned in the response — re-fetch later by passing that id back as `Idempotency-Key`). Only UUIDv4 is accepted.
+
+The response is markdown containing:
+- `Database ID`, `Endpoint`, `Token`
+- `Metrics` URL (JSON: uptime, commands, keys, throughput, memory, bandwidth)
+- `Expires` date
+- `Console URL` to share with the user (where they view usage and click **Claim** to keep the database)
+- An inline quickstart for the body-style REST API
+
+Parse these out of the markdown response and use them directly — there is no separate JSON envelope.
+
+## Calling the database (body-style REST)
+
+The returned endpoint speaks the Upstash Redis REST API. Prefer the **body-style** form: POST a JSON array as the body so you don't have to URL-encode the command.
+
+```bash
+# SET with TTL
+curl https://<endpoint> \
+  -H "Authorization: Bearer <token>" \
+  -d '["SET","session:abc","{\"step\":2}","EX","3600"]'
+
+# GET
+curl https://<endpoint> \
+  -H "Authorization: Bearer <token>" \
+  -d '["GET","session:abc"]'
+```
+
+You can also use the official SDKs against the same endpoint + token (`@upstash/redis` for TS/JS, `upstash-redis` for Python).
+
+## Common agent patterns
+
+| Need | Commands |
+|------|----------|
+| Short-term memory across tool calls in one run | `SET key value EX <ttl>` / `GET key` |
+| Conversation / turn-by-turn log | `LPUSH chat:<user> <json>` / `LRANGE chat:<user> 0 20` |
+| Sub-agent work queue (producer/consumer) | `LPUSH jobs <json>` / `RPOP jobs` |
+| Ranked memory (recent-first or score-first) | `ZADD memories <score> <member>` / `ZREVRANGE memories 0 9` |
+
+## Tell the user
+
+After provisioning, surface the **console URL** from the response to the user. Make clear that:
+- The database expires in 3 days.
+- They can view usage at the console URL and click **Claim** to keep it.
+- This is unauthenticated scratch storage — don't put secrets or PII in it.
+
+## Reference
+
+- Service entry point (also serves the `GET` doc): https://upstash.com/start-redis
+- Full REST API: https://upstash.com/docs/redis/features/restapi
+- TS/JS SDK: https://upstash.com/docs/redis/sdks/ts
+- Python SDK: https://upstash.com/docs/redis/sdks/py