@ragieai/skills 0.1.0

package/skills/ragie/references/mcp.md

@@ -0,0 +1,84 @@
+# Ragie MCP Server
+
+The Ragie MCP server exposes a `retrieve` tool scoped to a specific partition. Use it to search your knowledge base interactively from Claude Code — without writing code.
+
+## URL Pattern
+
+Each partition gets its own endpoint:
+
+```
+https://api.ragie.ai/mcp/{partition}
+```
+
+Examples:
+- `https://api.ragie.ai/mcp/debug` → `debug` partition
+- `https://api.ragie.ai/mcp/production` → `production` partition
+
+## Configuration
+
+### Via this plugin (recommended)
+
+Set environment variables before starting Claude Code:
+
+```bash
+export RAGIE_API_KEY=ragie_...
+export RAGIE_PARTITION=your-partition-name
+```
+
+The plugin's `.mcp.json` handles the rest automatically.
+
+### Manual project config
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ragie": {
+      "type": "http",
+      "url": "https://api.ragie.ai/mcp/your-partition",
+      "headers": {
+        "Authorization": "Bearer ${RAGIE_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Multiple partitions
+
+```json
+{
+  "mcpServers": {
+    "ragie-main": {
+      "type": "http",
+      "url": "https://api.ragie.ai/mcp/main",
+      "headers": { "Authorization": "Bearer ${RAGIE_API_KEY}" }
+    },
+    "ragie-debug": {
+      "type": "http",
+      "url": "https://api.ragie.ai/mcp/debug",
+      "headers": { "Authorization": "Bearer ${RAGIE_API_KEY}" }
+    }
+  }
+}
+```
+
+## The `retrieve` Tool
+
+Once the MCP server is connected, Claude can call `retrieve` directly.
+
+Example prompts:
+- *"Search my Ragie knowledge base for rate limit documentation"*
+- *"What does Ragie have indexed about authentication?"*
+- *"Retrieve the top 5 chunks about error handling and show me the scores"*
+
+## When to Use MCP vs SDK
+
+| Situation | Use |
+|-----------|-----|
+| Testing retrieval quality during development | MCP |
+| Exploring what's indexed in a partition | MCP |
+| Debugging poor search results | MCP |
+| Production application code | SDK (`client.retrievals.retrieve()`) |
+| Ingesting documents | SDK (MCP only exposes `retrieve`) |

package/skills/ragie/references/metadata-filtering.md

@@ -0,0 +1,149 @@
+# Ragie Metadata Filtering
+
+Metadata is arbitrary key-value pairs attached to documents at ingest time. Use them to filter retrieval to a relevant subset of documents.
+
+> Python user? See `references/python.md` for Python equivalents.
+
+## Attaching Metadata on Ingest
+
+```typescript
+await client.documents.createRaw({
+  content: contentBuffer,
+  contentType: "application/pdf",
+  name: "API Docs v3",
+  metadata: {
+    product: "api",
+    version: 3,          // numbers are allowed
+    active: true,        // booleans are allowed
+    tags: ["public", "stable"],  // list of strings is allowed
+  },
+});
+```
+
+Metadata values can be: **strings**, **numbers** (stored as 64-bit float), **booleans**, or **lists of strings**. Keys set to `null` in a patch operation are deleted.
+
+## Filtering at Retrieval
+
+### Simple equality (shorthand)
+
+```typescript
+const results = await client.retrievals.retrieve({
+  query: "rate limits",
+  filter: {
+    product: "api",
+    version: 3,
+  },
+});
+```
+
+All keys in a plain object filter must match — it's an implicit `$and` of equality checks.
+
+### Filter operators
+
+For range, set membership, and logical combinations use explicit operators:
+
+```typescript
+// Greater than / less than
+filter: { year: { $gt: 2022 } }
+filter: { score: { $gte: 0.8, $lte: 1.0 } }
+
+// Not equal
+filter: { status: { $ne: "draft" } }
+
+// In / not in a set
+filter: { lang: { $in: ["en", "fr"] } }
+filter: { env: { $nin: ["test", "staging"] } }
+
+// Logical OR
+filter: {
+  $or: [
+    { product: "api" },
+    { product: "dashboard" }
+  ]
+}
+
+// Logical AND with sub-conditions
+filter: {
+  $and: [
+    { product: "api" },
+    { version: { $gte: 2 } }
+  ]
+}
+```
+
+| Operator | Purpose | Supported types |
+|----------|---------|-----------------|
+| `$eq` | Equal | number, string, boolean |
+| `$ne` | Not equal | number, string, boolean |
+| `$gt` | Greater than | number only |
+| `$gte` | Greater than or equal | number only |
+| `$lt` | Less than | number only |
+| `$lte` | Less than or equal | number only |
+| `$in` | Value in array | string or number |
+| `$nin` | Value not in array | string or number |
+| `$and` | Logical AND | compound |
+| `$or` | Logical OR | compound |
+
+## Updating Metadata
+
+```typescript
+// Partial update — only specified keys are changed; keys set to null are deleted
+await client.documents.patchMetadata({
+  documentId: docId,
+  patchDocumentMetadataParams: { metadata: { reviewed: "true", version: 4 } },
+});
+```
+
+## Common Patterns
+
+### Product + version scoping
+
+```typescript
+// Tag by product and version on ingest
+await client.documents.createDocumentFromUrl({
+  url,
+  metadata: { product: "dashboard", version: 4 },
+});
+
+// Query only that version's docs
+const results = await client.retrievals.retrieve({
+  query: "usage metrics",
+  filter: { product: "dashboard", version: 4 },
+});
+```
+
+### Language filtering
+
+```typescript
+metadata: { lang: "fr" }
+filter: { lang: "fr" }
+```
+
+### Environment separation
+
+```typescript
+metadata: { env: "staging" }
+filter: { env: "staging" }
+```
+
+### Date range filtering
+
+```typescript
+// Store dates as Unix timestamps (numbers)
+metadata: { published_at: 1704067200 }
+
+// Query documents published after 2024-01-01
+filter: { published_at: { $gt: 1704067200 } }
+```
+
+## Metadata vs Partitions
+
+Metadata filtering and partitions serve different purposes — see `partitions.md` for the comparison.
+
+## Gotchas
+
+- Metadata values may be strings, numbers, booleans, or lists of strings. Numbers do **not** need to be stringified — use native numbers for range operators to work correctly.
+- Filtering on a key that doesn't exist on a document excludes that document from results.
+- Reserved keys (will cause a 422 error): `document_id`, `document_type`, `document_source`, `document_name`, `document_uploaded_at`. Keys beginning with `_` are also reserved.
+- Metadata filtering is a **pre-filter**: Ragie guarantees `top_k` results if they exist after filtering.
+- Up to 1000 total metadata values per document (each item in an array counts toward the total).

package/skills/ragie/references/partitions.md

@@ -0,0 +1,85 @@
+# Ragie Partitions
+
+Partitions are logical namespaces within a single Ragie account. Use them to isolate documents by tenant, environment, project, or any other boundary.
+
+> Python user? See `references/python.md` for Python equivalents.
+
+## Basic Usage
+
+```typescript
+// Ingest into a partition
+await client.documents.createDocumentFromUrl({
+  url: "https://example.com/doc",
+  partition: "tenant-42",
+});
+
+// Retrieve from that partition only
+const results = await client.retrievals.retrieve({
+  query: "pricing",
+  partition: "tenant-42",
+});
+```
+
+## Multi-Tenant Pattern
+
+```typescript
+function ingestForTenant(client: Ragie, tenantId: string, url: string) {
+  return client.documents.createDocumentFromUrl({
+    url,
+    partition: `tenant-${tenantId}`,
+  });
+}
+
+function retrieveForTenant(client: Ragie, tenantId: string, query: string) {
+  return client.retrievals.retrieve({
+    query,
+    partition: `tenant-${tenantId}`,
+    rerank: true,
+  });
+}
+```
+
+## Partition Management
+
+```typescript
+// List all partitions (returns a PageIterator — async iterable)
+for await (const page of client.partitions.list()) {
+  for (const partition of page.result.partitions) {
+    console.log(partition.id, partition.name);
+  }
+}
+
+// Create a partition explicitly
+await client.partitions.create({ name: "tenant-42", description: "optional" });
+// Note: partitions are also created implicitly on first document ingest
+
+// Get partition details and usage metrics (document count, pages processed)
+const detail = await client.partitions.get({ partitionId: "tenant-42" });
+
+// Set page limits (triggers webhook when limit is exceeded)
+await client.partitions.setLimits({
+  partitionId: "tenant-42",
+  partitionLimitParams: { pagesHostedLimitMonthly: 1000 },
+});
+
+// Delete a partition and all its documents
+await client.partitions.delete({ partitionId: "tenant-42" });
+```
+
+## Partitions vs Metadata Filters
+
+| | Partitions | Metadata filters |
+|-|------------|-----------------|
+| Isolation | Hard — separate index | Soft — same index, filtered at query time |
+| Use for | Multi-tenancy, environments | Document categories, versions, tags |
+| Performance | Fastest (no cross-partition scan) | Slightly slower on large corpora |
+| Deletion | Delete whole partition at once | Must delete documents individually |
+
+Use partitions for tenant isolation. Use metadata filters for sub-categorization within a tenant. See `metadata-filtering.md`.
+
+## Gotchas
+
+- Omitting `partition` on ingest places the document in the default partition.
+- Omitting `partition` on retrieval searches **only** the default partition — not all partitions.
+- Partition names are case-sensitive. `Tenant-42` and `tenant-42` are different partitions.
+- Deleting a partition is irreversible and deletes all documents within it.

package/skills/ragie/references/python.md

@@ -0,0 +1,232 @@
+# Ragie Python SDK
+
+The Python SDK mirrors the TypeScript SDK conceptually — same methods, snake_case naming.
+
+```bash
+pip install ragie
+```
+
+```python
+import os
+from ragie import Ragie
+
+client = Ragie(auth=os.environ["RAGIE_API_KEY"])
+```
+
+## Ingestion
+
+The Python SDK has three distinct methods depending on the source. Using the wrong one is a common source of errors.
+
+| Source | Method | Request class |
+|--------|--------|---------------|
+| File upload (all file types) | `documents.create()` | `ragie.CreateDocumentParams` + `ragie.File` |
+| In-memory data (text/JSON) | `documents.create_raw()` | `ragie.CreateDocumentRawParams` |
+| URL | `documents.create_document_from_url()` | `ragie.CreateDocumentFromURLParams` |
+
+**Prefer `documents.create()`** when uploading files from disk, as it supports all file types including binary formats. **Prefer `create_raw()`** when your data is already in memory as a string or dict — it is simpler and avoids unnecessary file wrapping, but only handles text and JSON.
+
+### From a file
+
+Use `documents.create()` with `ragie.File`. This is the only method that supports all file types including binary formats (PDF, DOCX, images, etc.).
+
+```python
+import ragie
+
+with open("doc.pdf", "rb") as f:
+    doc = client.documents.create(
+        request=ragie.CreateDocumentParams(
+            file=ragie.File(
+                file_name="doc.pdf",
+                content=f.read(),
+                content_type="application/pdf",
+            ),
+            name="Q4 Report",
+            partition="tenant-42",
+            metadata={"type": "report", "year": "2024"},
+        )
+    )
+```
+
+### From a URL
+
+```python
+import ragie
+
+doc = client.documents.create_document_from_url(
+    request=ragie.CreateDocumentFromURLParams(
+        url="https://example.com/report.pdf",
+        name="Q4 Report",
+        partition="tenant-42",
+        metadata={"type": "report", "year": "2024"},
+    )
+)
+```
+
+### From in-memory data (raw text or JSON)
+
+**Preferred when your data is already in memory** (e.g., scraped content, generated text, API responses). Accepts strings and dicts — not bytes.
+
+```python
+import ragie
+
+doc = client.documents.create_raw(
+    request=ragie.CreateDocumentRawParams(
+        data="Your text content here...",  # str or dict
+        name="my-note",
+        partition="tenant-42",
+    )
+)
+```
+
+## Polling for Readiness
+
+`documents.get()` returns `DocumentGet`, which is a **different type** from the `Document` returned by `create()` and `create_document_from_url()`. Both have `.status` and `.id`, but annotate them separately if you need type safety.
+
+```python
+import time
+from ragie.models import DocumentGet
+
+def wait_for_ready(client, doc_id: str, timeout: int = 120) -> None:
+    start = time.time()
+    while time.time() - start < timeout:
+        doc: DocumentGet = client.documents.get(document_id=doc_id)
+        if doc.status == "ready":
+            return
+        if doc.status == "failed":
+            raise RuntimeError(f"Document {doc_id} failed")
+        time.sleep(3)
+    raise TimeoutError(f"Document {doc_id} not ready after {timeout}s")
+```
+
+## Retrieval
+
+```python
+import ragie
+
+results = client.retrievals.retrieve(
+    request=ragie.RetrieveParams(
+        query="your question",
+        top_k=8,
+        rerank=True,
+        partition="tenant-42",
+        filter={"product": "api", "version": "v3"},
+    )
+)
+
+for chunk in results.scored_chunks:
+    print(chunk.text, chunk.score)
+    # also: chunk.document_id, chunk.document_name, chunk.document_metadata
+```
+
+## Document Management
+
+```python
+import ragie
+from ragie.models import DocumentGet
+
+# Get a document — returns DocumentGet, not Document
+doc: DocumentGet = client.documents.get(document_id=doc_id)
+
+# List documents — use ListDocumentsRequest, not keyword args
+# .result is a DocumentList object — access .result.documents for the list
+page = client.documents.list(
+    request=ragie.ListDocumentsRequest(partition="tenant-42", page_size=50)
+)
+docs = page.result.documents
+
+# Paginate
+while page is not None:
+    for doc in page.result.documents:
+        print(doc.id, doc.name)
+    page = page.next()  # .next() returns the next page or None
+
+# Update metadata (partial update — keyword args are required)
+client.documents.patch_metadata(
+    document_id=doc_id,
+    patch_document_metadata_params=ragie.PatchDocumentMetadataParams(
+        metadata={"reviewed": "true", "version": 4}
+    ),
+)
+
+# Delete a document (keyword args are required)
+client.documents.delete(document_id=doc_id)
+```
+
+## Bulk Ingestion (asyncio)
+
+The Python SDK has no `AsyncRagie` class. Use `async with Ragie(...) as client:` and call the `_async`-suffixed method variants.
+
+```python
+import asyncio
+import os
+import ragie
+from ragie import Ragie
+
+async def bulk_ingest(urls: list[str], partition: str):
+    async with Ragie(auth=os.environ["RAGIE_API_KEY"]) as client:
+        tasks = [
+            client.documents.create_document_from_url_async(
+                request=ragie.CreateDocumentFromURLParams(url=url, partition=partition)
+            )
+            for url in urls
+        ]
+        return await asyncio.gather(*tasks)
+```
+
+## RAG Response
+
+```python
+import anthropic
+import ragie
+
+ragie_client = Ragie(auth=os.environ["RAGIE_API_KEY"])
+claude = anthropic.Anthropic()
+
+def answer(question: str) -> str:
+    chunks = ragie_client.retrievals.retrieve(
+        request=ragie.RetrieveParams(query=question, rerank=True, top_k=6)
+    )
+    context = "\n\n".join(c.text for c in chunks.scored_chunks)
+    msg = claude.messages.create(
+        model="claude-sonnet-4-6",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": f"Context:\n{context}\n\nQuestion: {question}"}],
+    )
+    return msg.content[0].text
+
+def stream_answer(question: str) -> None:
+    chunks = ragie_client.retrievals.retrieve(
+        request=ragie.RetrieveParams(query=question, rerank=True, top_k=6)
+    )
+    context = "\n\n".join(c.text for c in chunks.scored_chunks)
+    with claude.messages.stream(
+        model="claude-sonnet-4-6",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": f"Context:\n{context}\n\nQuestion: {question}"}],
+    ) as stream:
+        for text in stream.text_stream:
+            print(text, end="", flush=True)
+```
+
+## Naming Differences vs TypeScript
+
+| TypeScript | Python |
+|------------|--------|
+| `createDocumentFromUrl()` | `create_document_from_url()` |
+| `createRaw()` | `create_raw()` |
+| `topK` | `top_k` |
+| `scoredChunks` | `scored_chunks` |
+| `documentId` | `document_id` |
+| `documentName` | `document_name` |
+| `contentType` | `content_type` |
+
+## Gotchas
+
+- **`ragie.File`, not `ragie.FileUpload`** — the file wrapper class is `ragie.File`. `FileUpload` does not exist.
+- **`ragie.ListDocumentsRequest`, not `ragie.ListDocumentsParams`** — always use the `Request` suffix for list operations.
+- **Prefer `create_raw()` for in-memory data** — it's simpler when you already have a string or dict. **Prefer `create()` for file uploads** — it supports all file types. `create_raw()` only handles text and JSON; binary files (PDF, DOCX, etc.) must use `create()` with `ragie.File`.
+- **`documents.list()` response requires `.result.documents`** — `.result` is a `DocumentList` object, not a list. Access `.result.documents` to get the actual `List[Document]`. Iterating `.result` directly yields Pydantic field tuples, not documents.
+- **`documents.get()` returns `DocumentGet`, not `Document`** — these are distinct types. Import `from ragie.models import DocumentGet` and annotate accordingly. Do not assign a `DocumentGet` to a variable typed as `Document`.
+- **Pagination via `.next()`** — call `page.next()` to get the next `ListDocumentsResponse`, or `None` if there are no more pages.
+- **Keyword-only arguments** — `delete`, `patch_metadata`, and similar methods use keyword-only args (`*` in signature). Always pass `document_id=doc_id`, never positionally.
+- **No `AsyncRagie` class** — there is only `Ragie`. For async usage, open it as a context manager (`async with Ragie(...) as client:`) and call `_async`-suffixed methods: `create_async()`, `create_document_from_url_async()`, `create_raw_async()`, etc.

package/skills/ragie/references/quickstart.md

@@ -0,0 +1,69 @@
+# Ragie Quickstart
+
+> Python user? See `references/python.md` for Python equivalents.
+
+## Get an API Key
+
+Sign up at [ragie.ai](https://ragie.ai) and copy the API key from the dashboard.
+
+## Install the SDK
+
+```bash
+npm install ragie
+```
+
+## Ingest a Document
+
+```typescript
+import { Ragie } from "ragie";
+import { openAsBlob } from "fs";
+
+const client = new Ragie({ auth: process.env.RAGIE_API_KEY });
+
+// From a file (supports all file types: PDF, DOCX, images, …)
+const doc = await client.documents.create({
+  file: await openAsBlob("report.pdf"),
+  name: "report.pdf",
+});
+
+// From in-memory data (preferred when data is already a string/object)
+const doc2 = await client.documents.createRaw({
+  data: "Your text content here...",
+  name: "my-note",
+});
+
+console.log(doc.id, doc.status); // status: "pending" → "ready"
+// Use createRaw() for in-memory text/JSON; use create() for file uploads (all file types supported)
+```
+
+See `ingestion.md` for URL ingestion, polling, webhooks, and bulk patterns.
+
+## Retrieve (Search)
+
+```typescript
+const results = await client.retrievals.retrieve({
+  query: "What are the key findings?",
+  rerank: true,
+});
+for (const chunk of results.scoredChunks) {
+  console.log(chunk.text, chunk.score);
+}
+```
+
+## Environment Setup
+
+Always load the API key from the environment:
+
+```bash
+export RAGIE_API_KEY=ragie_...
+```
+
+```typescript
+import { Ragie } from "ragie";
+const client = new Ragie({ auth: process.env.RAGIE_API_KEY });
+```
+
+## Gotchas
+
+- Documents process **asynchronously** — `status` starts as `pending`, transitions to `ready`. Don't query before it's ready. See `ingestion.md` for polling/webhook patterns.
+- `rerank: true` significantly improves result quality. Always enable it for generation use cases unless latency is critical.