@ragieai/skills 0.1.0

package/skills/ragie/references/rag-patterns.md

@@ -0,0 +1,160 @@
+# RAG Patterns with Ragie
+
+> Python user? See `references/python.md` for Python equivalents.
+
+## Basic RAG Response
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+import { Ragie } from "ragie";
+
+const ragie = new Ragie({ auth: process.env.RAGIE_API_KEY });
+const anthropic = new Anthropic();
+
+async function answer(question: string): Promise<string> {
+  const results = await ragie.retrievals.retrieve({
+    query: question,
+    rerank: true,
+    topK: 6,
+  });
+  const context = results.scoredChunks.map((c) => c.text).join("\n\n");
+
+  const msg = await anthropic.messages.create({
+    model: "claude-sonnet-4-6",
+    max_tokens: 1024,
+    messages: [{ role: "user", content: `Context:\n${context}\n\nQuestion: ${question}` }],
+  });
+  return (msg.content[0] as { text: string }).text;
+}
+```
+
+## Streaming
+
+```typescript
+async function streamAnswer(question: string): Promise<void> {
+  const results = await ragie.retrievals.retrieve({
+    query: question,
+    rerank: true,
+    topK: 6,
+  });
+  const context = results.scoredChunks.map((c) => c.text).join("\n\n");
+
+  const stream = await anthropic.messages.stream({
+    model: "claude-sonnet-4-6",
+    max_tokens: 1024,
+    messages: [{ role: "user", content: `Context:\n${context}\n\nQuestion: ${question}` }],
+  });
+  for await (const chunk of stream) {
+    if (chunk.type === "content_block_delta" && chunk.delta.type === "text_delta") {
+      process.stdout.write(chunk.delta.text);
+    }
+  }
+}
+```
+
+## Citations
+
+```typescript
+async function answerWithCitations(question: string) {
+  const results = await ragie.retrievals.retrieve({
+    query: question,
+    rerank: true,
+    topK: 6,
+  });
+
+  const sources = results.scoredChunks.map((c) => ({
+    name: c.documentName,
+    id: c.documentId,
+  }));
+  const context = results.scoredChunks
+    .map((c) => `[Source: ${c.documentName}]\n${c.text}`)
+    .join("\n\n");
+
+  const msg = await anthropic.messages.create({
+    model: "claude-sonnet-4-6",
+    max_tokens: 1024,
+    messages: [{
+      role: "user",
+      content: `Answer using only the context below. Reference sources by name.\n\nContext:\n${context}\n\nQuestion: ${question}`,
+    }],
+  });
+
+  return { answer: (msg.content[0] as { text: string }).text, sources };
+}
+```
+
+## Tool Use Integration
+
+Expose Ragie as a tool Claude can call during an agentic loop:
+
+```typescript
+const tools: Anthropic.Tool[] = [{
+  name: "search_knowledge_base",
+  description: "Search the internal knowledge base for relevant information.",
+  input_schema: {
+    type: "object",
+    properties: { query: { type: "string", description: "The search query" } },
+    required: ["query"],
+  },
+}];
+
+async function runAgent(userMessage: string): Promise<string> {
+  const messages: Anthropic.MessageParam[] = [{ role: "user", content: userMessage }];
+
+  while (true) {
+    const response = await anthropic.messages.create({
+      model: "claude-sonnet-4-6",
+      max_tokens: 2048,
+      tools,
+      messages,
+    });
+
+    if (response.stop_reason === "tool_use") {
+      const toolUse = response.content.find((b) => b.type === "tool_use") as Anthropic.ToolUseBlock;
+      const { query } = toolUse.input as { query: string };
+      const results = await ragie.retrievals.retrieve({ query, rerank: true });
+      const context = results.scoredChunks.map((c) => c.text).join("\n\n");
+
+      messages.push(
+        { role: "assistant", content: response.content },
+        { role: "user", content: [{ type: "tool_result", tool_use_id: toolUse.id, content: context }] }
+      );
+    } else {
+      const text = response.content.find((b) => b.type === "text") as Anthropic.TextBlock;
+      return text.text;
+    }
+  }
+}
+```
+
+## Multi-Tenant RAG
+
+```typescript
+async function answerForTenant(tenantId: string, question: string): Promise<string> {
+  const results = await ragie.retrievals.retrieve({
+    query: question,
+    partition: `tenant-${tenantId}`,
+    rerank: true,
+  });
+  const context = results.scoredChunks.map((c) => c.text).join("\n\n");
+
+  const msg = await anthropic.messages.create({
+    model: "claude-sonnet-4-6",
+    max_tokens: 1024,
+    messages: [{ role: "user", content: `Context:\n${context}\n\nQuestion: ${question}` }],
+  });
+  return (msg.content[0] as { text: string }).text;
+}
+```
+
+## Production Checklist
+
+- [ ] API key in environment variable, not source code
+- [ ] `rerank: true` for generation use cases
+- [ ] Document readiness verified before querying (polling or webhook)
+- [ ] Partitions used for multi-tenant isolation
+- [ ] Metadata attached for future filtering
+- [ ] Retry on 429 / 5xx with exponential back-off
+- [ ] Citations surfaced in answers
+- [ ] `topK` tuned to use case (6–10 is typical)
+- [ ] Chunk scores logged for retrieval quality monitoring

package/skills/ragie/references/retrieval.md

@@ -0,0 +1,77 @@
+# Ragie Retrieval
+
+> Python user? See `references/python.md` for Python equivalents.
+
+## Basic Retrieval
+
+```typescript
+const results = await client.retrievals.retrieve({
+  query: "What are the rate limits?",
+});
+for (const chunk of results.scoredChunks) {
+  console.log(chunk.text, chunk.score);
+}
+```
+
+## Full Options
+
+```typescript
+const results = await client.retrievals.retrieve({
+  query: "your question",
+  topK: 8,                      // number of chunks returned (default 8)
+  rerank: true,                 // cross-encoder rerank — improves quality significantly
+  partition: "tenant-42",       // scope to a partition (optional)
+  filter: {                     // metadata filter (optional) — see metadata-filtering.md
+    product: "api",
+    version: "v3",
+  },
+  maxChunksPerDocument: 2,      // limit chunks per source doc — improves source diversity (optional)
+  recencyBias: false,           // favor more recently ingested documents (default false) (optional)
+});
+```
+
+## Scored Chunk Fields
+
+Each item in `scoredChunks` has:
+
+| Field | Description |
+|-------|-------------|
+| `text` | The chunk text |
+| `score` | Relevance score (higher = more relevant) |
+| `documentId` | ID of the source document |
+| `documentName` | Display name of the source document |
+| `documentMetadata` | Metadata attached to the source document |
+| `id` | The chunk's own ID |
+| `index` | The chunk's position index within the document |
+| `metadata` | Chunk-level metadata (distinct from `documentMetadata`) |
+
+## Hybrid Search
+
+Ragie automatically blends semantic (vector) and keyword (BM25) search on every query. No configuration needed.
+
+`rerank: true` applies a cross-encoder on top of the hybrid results. Always enable for generation use cases:
+
+```typescript
+// Fast path — lower latency
+const fast = await client.retrievals.retrieve({ query: q, rerank: false });
+
+// Quality path — recommended for RAG
+const best = await client.retrievals.retrieve({ query: q, rerank: true });
+```
+
+## Tuning topK
+
+| Use case | Recommended topK |
+|----------|------------------|
+| Short-answer generation | 4–6 |
+| Long-form generation | 8–12 |
+| Exploratory / debugging | 20+ |
+
+Too many chunks dilutes the context and increases token cost. Too few risks missing relevant content.
+
+## Gotchas
+
+- `rerank` adds ~100–300ms latency but meaningfully improves result quality. Use it by default.
+- Metadata `filter` supports rich operators (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$and`, `$or`). Simple object shorthand `{ key: value }` is equality. See `metadata-filtering.md`.
+- Scores are not normalized across queries; use them for ranking within a single result set, not across queries.
+- Query documents only after `status === "ready"`. See `ingestion.md`.