zilmate 1.8.0 → 1.8.5

package/.agents/skills/upstash-vector-js/features/namespaces.md

@@ -0,0 +1,32 @@
+# Vector Feature: Namespaces
+
+Namespaces partition a single Upstash Vector index into fully isolated subsets. Each request executes only within its specified namespace.
+
+## Key Concepts
+
+- Every index has a default namespace named "" (empty string).
+- Additional namespaces are created automatically on first upsert.
+- If no namespace is provided, all operations use the default.
+
+## Using Namespaces
+
+Upsert and query operations scoped to a namespace automatically create it if missing.
+
+```ts
+import { Index } from "@upstash/vector";
+const index = new Index({ url: "URL", token: "TOKEN" });
+const ns = index.namespace("ns");
+await ns.upsert({ id: "id-0", vector: [0.1, 0.2] });
+await ns.query({ vector: [0.1, 0.2], topK: 5 });
+```
+
+## Operatoins
+
+```ts
+await index.deleteNamespace("ns");
+await index.listNamespaces();
+```
+
+## Common Pitfalls
+
+- Forgetting to specify `namespace` causes writes to go into the default namespace.

package/.agents/skills/upstash-vector-js/sdk-methods.md

@@ -0,0 +1,210 @@
+# Vector TS SDK
+
+## Upsert
+
+Add or update vectors. Also accepts raw text (`data`) to embed automatically.
+
+**Pitfalls**
+
+- Vector dimension must match index dimension.
+- Passing both `vector` and `data` is invalid.
+- Metadata is optional but recommended for filtering.
+
+**Example (single + batch, mix of vector/data)**
+
+```ts
+// Single vector
+await index.upsert({ id: "1", vector: [0.1, 0.2], metadata: { type: "doc" } });
+
+// Multiple vectors
+await index.upsert(
+  [
+    { id: "2", vector: [0.2, 0.3] },
+    { id: "3", vector: [0.3, 0.4], metadata: { tag: "a" } },
+  ],
+  { namespace: "ns" }
+);
+
+// Using data (auto‑embedding. Only works if the vector index has an embedding model)
+await index.upsert({ id: "4", data: "A fantasy movie" });
+```
+
+---
+
+## Fetch
+
+Retrieve vectors by exact ID or prefix.
+
+**Example**
+
+```ts
+// Exact
+const out = await index.fetch(["1", "2"], { includeMetadata: true });
+// → [{ id: "1", metadata: {...} }, null]
+
+// Prefix
+await index.fetch({ prefix: "user-" });
+```
+
+---
+
+## Delete
+
+Remove vectors by IDs, prefix, or metadata filter.
+
+**Pitfalls**
+
+- Only one of `ids`, `prefix`, or `filter` can be used.
+- Using `filter` triggers an O(N) scan.
+
+**Example**
+
+```ts
+await index.delete(["1", "2"]);
+await index.delete({ prefix: "user-" });
+await index.delete({ filter: "status = 'expired'" });
+```
+
+---
+
+## Query
+
+Find the top‑K most similar vectors. Supports dense, sparse, hybrid, and embedded-on-demand queries.
+
+**Pitfalls**
+
+- Query vector dimension must match index.
+- Scores are normalized 0–1 no matter the similarity metric.
+
+**Example**
+
+```ts
+// Dense vector
+const results = await index.query({
+  vector: [0.1, 0.2],
+  topK: 3,
+  includeMetadata: true,
+  filter: "genre = 'fantasy'",
+});
+
+// Data (auto‑embedding)
+await index.query({ data: "epic fantasy adventure", topK: 2 });
+```
+
+---
+
+## Resumable Query
+
+Long-running, chunked queries with server-side state.
+
+**Pitfalls**
+
+- Remember to call `stop()` to free resources.
+- `fetchNext(k)` retrieves N more results.
+
+**Example**
+
+```ts
+const { result, fetchNext, stop } = await index.resumableQuery({
+  vector: [0.1, 0.2],
+  topK: 50,
+  maxIdle: 3600,
+});
+
+const next = await fetchNext(10);
+await stop();
+```
+
+---
+
+## Range
+
+Paginated, stateless scanning of vectors; recommended for large prefix fetches.
+
+**Pitfalls**
+
+- Always pass `cursor`; set to `0` initially.
+
+**Example**
+
+```ts
+let cursor = 0;
+while (cursor !== null) {
+  const page = await index.range({ cursor, limit: 100, includeMetadata: true });
+  console.log(page.vectors);
+  cursor = page.nextCursor;
+}
+```
+
+---
+
+## Info
+
+Retrieve index statistics.
+
+**Example**
+
+```ts
+const info = await index.info();
+/* Returns:
+{
+  vectorCount: number;
+  pendingVectorCount: number;
+  indexSize: number;
+  dimension: number;
+  similarityFunction: "COSINE" | "EUCLIDEAN" | "DOT_PRODUCT";
+  denseIndex?: {
+    dimension: number;
+    similarityFunction: "COSINE" | "EUCLIDEAN" | "DOT_PRODUCT";
+    embeddingModel?: string;
+  };
+  sparseIndex?: {
+    embeddingModel?: string;
+  };
+  namespaces: Record<string, {
+    vectorCount: number;
+    pendingVectorCount: number;
+  }>;
+}
+*/
+```
+
+---
+
+## Reset
+
+Clear a namespace or the entire index.
+
+**Pitfalls**
+
+- `{ all: true }` must be explicit.
+
+**Example**
+
+```ts
+await index.reset(); // default namespace
+await index.reset({ namespace: "my-namespace" });
+await index.reset({ all: true });
+```
+
+---
+
+## Advanced
+
+### Request Timeout
+
+```ts
+const index = new Index({
+  url,
+  token,
+  signal: () => AbortSignal.timeout(1000),
+});
+```
+
+### Telemetry
+
+Disable with env variable:
+
+```sh
+UPSTASH_DISABLE_TELEMETRY=1
+```

package/.agents/skills/upstash-workflow-js/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: upstash-workflow-js
+description: Skills for the Upstash Workflow TypeScript/JavaScript SDK to define, trigger, and manage workflows. Use this Skill whenever a user wants to create workflow endpoints, run steps, or interact with the Upstash Workflow client.
+---
+
+# Upstash Workflow SDK
+
+## Quick Start
+
+The Upstash Workflow SDK lets you expose serverless workflow endpoints and run them reliably using QStash under the hood.
+
+Install:
+
+```bash
+npm install @upstash/workflow
+```
+
+Define a simple workflow endpoint:
+
+```ts
+import { serve } from "@upstash/workflow";
+
+export const { POST } = serve(async (context) => {
+  await context.run("step-1", () => console.log("step 1"));
+  await context.run("step-2", () => console.log("step 2"));
+});
+```
+
+Trigger it from your backend:
+
+```ts
+import { Client } from "@upstash/workflow";
+
+const client = new Client({ token: process.env.QSTASH_TOKEN! });
+await client.trigger({ url: "https://your-app.com/api/workflow" });
+```
+
+## Other Skill Files
+
+These files contain the full documentation. Use them for details, patterns, and advanced behavior.
+
+- basics:
+  - **basics/serve** – How to expose workflow endpoints.
+  - **basics/context** – Full API for workflow `context` (steps, waits, webhooks, events, invoke, etc.).
+  - **basics/client** – Using the Workflow client to trigger, cancel, inspect, and notify runs.
+- features:
+  - **features/invoke** – Cross‑workflow invocation.
+  - **features/reliability** – Retries, failure callbacks, and DLQ.
+  - **features/flow-control** – Rate limits, concurrency, and parallelism.
+  - **features/wait-for-event** – Notify and wait-for-event patterns.
+  - **features/webhooks** – Webhook creation and consumption.
+- how to:
+  - **how-to/local-dev** – Local QStash dev server (auto via `QSTASH_DEV=true`) and tunneling.
+  - **how-to/realtime** – Realtime and human‑in‑the‑loop workflows.
+  - **how-to/migrations** – Migrating workflows safely.
+  - **how-to/middleware** – Adding middleware to workflows.
+- other files:
+  - **rest-api** – Low-level REST endpoints for interacting with QStash/Workflow.
+  - **troubleshooting** – Common debugging and environment issues.
+  - **agents** – Using Workflow with agents, orchestrators, and automation patterns.

package/.agents/skills/upstash-workflow-js/agents.md

@@ -0,0 +1,248 @@
+---
+name: workflow-agents
+description: Skill for building, configuring, and orchestrating Upstash Workflow Agents. Use when the user mentions agent workflows, multi-agent collaboration, tools, tasks, Upstash Workflow, or patterns like evaluator-optimizer, prompt chaining, parallelization, or orchestrator-workers.
+---
+
+# Workflow Agents
+
+This Skill provides guidance for defining and orchestrating agents, tools, models, and tasks inside **Upstash Workflow** using **TypeScript**. It explains core concepts, common patterns, workflow configuration, and pitfalls.
+
+## Quick Overview
+
+Use this Skill when:
+
+- Building agents with tools and backgrounds
+- Creating multi-step or multi-agent tasks
+- Implementing patterns like evaluator-optimizer or prompt chaining
+- Integrating LangChain or AI SDK tools
+- Running workflows reliably inside Upstash Workflow
+
+The Workflow Agents API centers around four elements:
+
+- **Models** — LLM providers (OpenAI, Anthropic, or any AI SDK provider)
+- **Tools** — Functions agents can call
+- **Agents** — LLM instances with background, maxSteps, and tools
+- **Tasks** — Executable prompts assigned to one or more agents
+
+---
+
+# Defining Models
+
+A model defines which provider the agent uses and includes optional configuration for retries, timeouts, or rate‑limits.
+
+```ts
+const agents = agentWorkflow(context);
+
+// Basic OpenAI model
+const model = agents.openai("gpt-3.5-turbo");
+
+// OpenAI-compatible provider
+const deepseek = agents.openai("deepseek-chat", {
+  baseURL: "https://api.deepseek.com",
+  apiKey: process.env.DEEPSEEK_API_KEY,
+});
+
+// AI SDK provider (ex: Anthropic)
+const anthropic = agents.AISDKModel({
+  context,
+  provider: createAnthropic, // imported from @ai-sdk/anthropic
+  providerParams: { apiKey: process.env.ANTHROPIC_KEY },
+  agentCallParams: {
+    timeout: 1000,
+    retries: 0,
+  },
+});
+```
+
+**Key parameters:**
+
+- **callSettings / agentCallParams** — timeout, retries, flow control
+- **provider / providerParams** — when using AI SDK providers
+
+**Pitfall:** If you use an OpenAI-compatible provider, you **must** set `baseURL`.
+
+---
+
+# Defining Tools
+
+Tools extend what agents can do. Workflow supports:
+
+- WorkflowTool (native)
+- AI SDK tools
+- LangChain tools
+- Agentic toolkits
+
+```ts
+import { z } from "zod";
+import { tool } from "ai";
+import { WorkflowTool } from "@upstash/workflow-agents";
+import { WikipediaQueryRun } from "@langchain/community/tools/wikipedia_query_run";
+
+const mathTool = tool({
+  description: "Evaluate a math expression",
+  parameters: z.object({ expression: z.string() }),
+  execute: async ({ expression }) => mathjs.evaluate(expression),
+});
+
+const workflowMath = new WorkflowTool({
+  description: "Evaluate math (workflow step aware)",
+  schema: z.object({ expression: z.string() }),
+  invoke: async ({ expression }) => mathjs.evaluate(expression),
+  executeAsStep: false, // allows context.call, etc.
+});
+
+const wikiTool = new WikipediaQueryRun({
+  topKResults: 1,
+  maxDocContentLength: 500,
+});
+```
+
+**Common mistakes:**
+
+- Workflow wraps execute/invoke in `context.run` by default, so you **cannot use context.call** unless `executeAsStep: false` is set.
+- LangChain tools must return **strings**, not objects.
+
+---
+
+# Defining Agents
+
+Agents wrap a model and add behavior via:
+
+- `maxSteps` — how many LLM calls the agent is allowed to make
+- `background` — system prompt
+- `tools` — available actions
+
+```ts
+const generator = agents.agent({
+  model,
+  name: "generator",
+  maxSteps: 1,
+  background: "Generate text from prompts.",
+  tools: {},
+});
+
+const evaluator = agents.agent({
+  model,
+  name: "evaluator",
+  maxSteps: 1,
+  background: "Evaluate responses and give corrections.",
+  tools: {},
+});
+```
+
+**Tips:**
+
+- Pick maxSteps carefully; too low prevents tool use; too high increases cost.
+- Names appear in Upstash Console logs; keep them descriptive.
+
+---
+
+# Tasks (Single & Multi Agent)
+
+A **task** is a single execution of an agent or a group of agents.
+
+```ts
+// Single agent task
+const single = agents.task({
+  agent: generator,
+  prompt: "Explain quantum mechanics.",
+});
+const { text } = await single.run();
+
+// Multi-agent with manager agent
+const multi = agents.task({
+  model, // manager LLM
+  agents: [generator, evaluator],
+  maxSteps: 3,
+  prompt: "Generate text and refine it until quality improves.",
+});
+const result = await multi.run();
+```
+
+**Tip:** In multi-agent mode, the model becomes a "manager" system that decides which agent to call.
+
+---
+
+# Common Agent Patterns
+
+Below are the patterns supported by the source files in this skill.
+
+## Prompt Chaining
+
+Sequential agent calls where each output becomes the next input.
+Useful for: stepwise research, multi‑stage content generation, breaking down complex tasks.
+
+Pitfall: watch `maxSteps` for agents that need both tool calls and summarization.
+
+## Evaluator‑Optimizer
+
+Loop until evaluator returns a PASS. Simple feedback‑refinement pattern.
+
+Pitfall: Always check evaluator output with `.includes("PASS")`, not strict equality.
+
+## Parallelization
+
+Use multiple agents with `Promise.all` and then aggregate.
+
+Pitfall: Avoid extremely large aggregated prompts; summarizing before combining is recommended.
+
+## Orchestrator‑Workers
+
+Manager delegates sub‑tasks to specialized workers.
+Useful for structured Q&A, multi‑topic analysis, or complex synthesis.
+
+Pitfall: The manager must have enough `maxSteps` to orchestrate multiple workers.
+
+---
+
+# Best Practices
+
+- Give each agent a _clear_ background; ambiguous roles cause incorrect tool use.
+- Define tools with strict schemas so LLMs call them reliably.
+- Use multi-agent tasks when the problem requires specialization.
+- Inspect console logs to debug tool calls and agent decisions.
+- Use local QStash dev server during development to avoid rate limits.
+
+---
+
+# Example: Combined Setup (models + tools + agents + tasks)
+
+This shows all core fields together in one concise example.
+
+```ts
+export const { POST } = serve(async (context) => {
+  const agents = agentWorkflow(context);
+  const model = agents.openai("gpt-4o");
+
+  const mathTool = tool({
+    description: "Compute math",
+    parameters: z.object({ expression: z.string() }),
+    execute: async ({ expression }) => mathjs.evaluate(expression),
+  });
+
+  const researcher = agents.agent({
+    model,
+    name: "researcher",
+    maxSteps: 2,
+    background: "Research topics using wiki.",
+    tools: { wikiTool },
+  });
+
+  const mathematician = agents.agent({
+    model,
+    name: "math",
+    maxSteps: 2,
+    background: "Solve numeric problems.",
+    tools: { mathTool },
+  });
+
+  const task = agents.task({
+    model, // manager
+    agents: [researcher, mathematician],
+    maxSteps: 3,
+    prompt: "Tell me about 3 stars and compute the sum of their masses.",
+  });
+
+  return (await task.run()).text;
+});
+```