schift-cli 0.1.0__py3-none-any.whl

schift_cli/data/schift-best-practices/references/bucket-upload.md

@@ -0,0 +1,116 @@
+---
+title: Bucket Upload for Document Ingestion
+impact: HIGH
+impactDescription: Manual chunking and embedding pipelines are error-prone and skip OCR, layout parsing, and deduplication that the bucket pipeline performs automatically. Using bucket.upload() reduces ingestion code from ~50 lines to 2.
+tags: [bucket, upload, ingestion, ocr, chunking, pdf, docx]
+---
+
+## Use bucket.upload() for Document Ingestion
+
+Schift buckets provide a fully managed ingestion pipeline: upload raw files and the bucket handles OCR, chunking, embedding, and FAISS index updates automatically. Building this pipeline manually duplicates work the platform already does and introduces subtle inconsistencies (chunk overlap, encoding issues, missed page breaks).
+
+Supported formats: **PDF, DOCX, TXT, MD**, and images (PNG, JPG, WEBP) with automatic OCR.
+
+### Incorrect
+
+```python
+# Python - manual pipeline: reads file, chunks, embeds, adds to collection
+import os
+from schift import Schift
+
+client = Schift()
+
+def ingest_pdf(file_path: str, collection_id: str):
+    # Step 1: extract text manually (no layout awareness, no OCR for scanned pages)
+    import PyPDF2
+    with open(file_path, "rb") as f:
+        reader = PyPDF2.PdfReader(f)
+        full_text = " ".join(page.extract_text() for page in reader.pages)
+
+    # Step 2: chunk manually (naive split, loses sentence boundaries)
+    chunk_size = 500
+    chunks = [full_text[i:i+chunk_size] for i in range(0, len(full_text), chunk_size)]
+
+    # Step 3: embed each chunk (no deduplication, no credit hold)
+    embeddings = client.embed_batch(chunks)
+
+    # Step 4: add to collection (separate API call per chunk batch)
+    for chunk, embedding in zip(chunks, embeddings.vectors):
+        client.collection.add(collection_id, text=chunk, vector=embedding)
+```
+
+```typescript
+// TypeScript - same manual approach
+import { Schift } from '@schift-io/sdk';
+import * as fs from 'fs';
+
+const client = new Schift();
+
+async function ingestPdf(filePath: string, collectionId: string) {
+  // manual extraction, chunking, embedding, and indexing
+  const text = extractTextFromPdf(filePath);              // not shown, error-prone
+  const chunks = splitIntoChunks(text, 500);              // naive chunker
+  const embeddings = await client.embedBatch(chunks);
+  for (const [chunk, vec] of zip(chunks, embeddings.vectors)) {
+    await client.collection.add(collectionId, { text: chunk, vector: vec });
+  }
+}
+```
+
+This approach misses scanned-page OCR, skips layout heuristics (headers, tables, footnotes), does no deduplication on re-upload, and requires maintaining the chunking logic yourself.
+
+### Correct
+
+```python
+# Python - bucket.upload() handles the entire pipeline
+import os
+from schift import Schift
+
+client = Schift()
+
+# Create the bucket once (idempotent name)
+bucket = client.bucket.create("legal-contracts")
+
+# Upload one or many files; returns immediately with a job ID
+job = client.bucket.upload(
+    bucket.id,
+    files=["contracts/acme_2026.pdf", "contracts/globex_2026.pdf"]
+)
+
+# Optional: poll until ingestion completes before searching
+job.wait()  # blocks until all files are indexed
+
+# Search across all uploaded documents
+results = client.bucket.search(bucket.id, "indemnification clause")
+for r in results.hits:
+    print(r.text, r.score)
+```
+
+```typescript
+// TypeScript - same two-step pattern
+import { Schift } from '@schift-io/sdk';
+import * as fs from 'fs';
+
+const client = new Schift();
+
+const bucket = await client.bucket.create('legal-contracts');
+
+const job = await client.bucket.upload(bucket.id, {
+  files: ['contracts/acme_2026.pdf', 'contracts/globex_2026.pdf'],
+});
+
+await job.wait(); // optional: wait for indexing to complete
+
+const results = await client.bucket.search(bucket.id, 'indemnification clause');
+results.hits.forEach(r => console.log(r.text, r.score));
+```
+
+**Credit hold pattern**: `bucket.upload()` pre-deducts an estimated token cost at upload time (a hold), then refunds the difference once actual usage is measured. You are never charged more than the hold amount. This prevents quota overruns during large uploads.
+
+**Re-upload deduplication**: Uploading the same file content twice to the same bucket is a no-op — Schift detects the content hash and skips re-embedding.
+
+## Reference
+
+- https://docs.schift.io/buckets/upload
+- https://docs.schift.io/buckets/supported-formats
+- https://docs.schift.io/billing/credit-hold

schift_cli/data/schift-best-practices/references/chatbot-widget.md

@@ -0,0 +1,238 @@
+---
+title: Build a Chatbot with Schift Search and Conversation Memory
+impact: LOW
+impactDescription: Production-ready chatbot with proper conversation context
+tags:
+  - chatbot
+  - rag
+  - conversation
+  - memory
+  - search
+  - llm
+---
+
+## Build a Chatbot with Schift Search and Conversation Memory
+
+A chatbot backed by Schift needs two things working together: vector search that retrieves relevant context from your data, and conversation history that lets the LLM give coherent follow-up answers. The most common mistake is only sending the latest user message — the LLM has no context for follow-ups like "tell me more" or "what about the second point?".
+
+Use a retrieve-then-generate pattern:
+1. User sends a message
+2. Backend searches a Schift collection using the user's query
+3. Retrieved chunks + conversation history are assembled into an LLM prompt
+4. LLM generates a response via Schift's OpenAI-compatible proxy at `/v1/llm/chat/completions`
+5. The conversation turn is stored in session
+
+### Incorrect
+
+Sending only the latest message to search and ignoring conversation history:
+
+```typescript
+// TypeScript — loses context on every turn
+app.post('/api/chat', async (c) => {
+  const { message } = await c.req.json();
+
+  // Only uses the current message — no history
+  const results = await client.search('col_...', message);
+  const context = results.map(r => r.text).join('\n');
+
+  // LLM has no idea what was said before
+  const response = await fetch('https://api.schift.io/v1/llm/chat/completions', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${process.env.SCHIFT_API_KEY}` },
+    body: JSON.stringify({
+      model: 'gpt-4o-mini',
+      messages: [
+        { role: 'system', content: `Answer using this context:\n${context}` },
+        { role: 'user', content: message },  // only the latest message
+      ],
+    }),
+  });
+  // ...
+});
+```
+
+```python
+# Python — same problem: no history, no context carryover
+@app.post("/api/chat")
+async def chat(body: ChatRequest):
+    results = client.search("col_...", body.message)  # no history used
+    context = "\n".join(r.text for r in results)
+    # Stateless: every call is a fresh conversation
+```
+
+Without history, the LLM cannot answer follow-ups, cannot refer back to earlier responses, and produces answers that feel disconnected and robotic.
+
+### Correct
+
+Maintain session-based conversation history, use the last 3–5 messages for search context, and pass full history to the LLM:
+
+```typescript
+// server.ts — Hono backend with session memory and Schift RAG
+import { Hono } from 'hono';
+import { Schift } from '@schift-io/sdk';
+
+const app = new Hono();
+const client = new Schift({ apiKey: process.env.SCHIFT_API_KEY! });
+
+// In-memory session store (swap for Redis in production)
+const sessions = new Map<string, Array<{ role: string; content: string }>>();
+
+const COLLECTION_ID = 'col_your_collection';
+const SCHIFT_LLM_URL = 'https://api.schift.io/v1/llm/chat/completions';
+
+app.post('/api/chat', async (c) => {
+  const { message, sessionId } = await c.req.json<{
+    message: string;
+    sessionId: string;
+  }>();
+
+  // 1. Load or initialize conversation history for this session
+  const history = sessions.get(sessionId) ?? [];
+
+  // 2. Build search query from current message + last 2 turns for context
+  //    This helps disambiguate follow-ups like "tell me more about that"
+  const recentContext = history
+    .slice(-4)  // last 2 user+assistant pairs
+    .map(m => m.content)
+    .join(' ');
+  const searchQuery = `${recentContext} ${message}`.trim();
+
+  // 3. Retrieve relevant chunks from Schift
+  const results = await client.search(COLLECTION_ID, searchQuery, {
+    topK: 4,
+    scoreThreshold: 0.70,
+  });
+  const retrievedContext = results.map(r => r.text).join('\n\n');
+
+  // 4. Assemble messages: system prompt + history + new user message
+  //    Keep last 10 turns to stay within token limits
+  const trimmedHistory = history.slice(-10);
+  const messages = [
+    {
+      role: 'system',
+      content: [
+        'You are a helpful assistant. Answer based on the provided context.',
+        'If the context does not contain the answer, say so honestly.',
+        '',
+        '## Context',
+        retrievedContext || '(no relevant context found)',
+      ].join('\n'),
+    },
+    ...trimmedHistory,
+    { role: 'user', content: message },
+  ];
+
+  // 5. Call LLM via Schift's OpenAI-compatible proxy
+  //    /v1/llm/chat/completions supports the same format as OpenAI
+  const llmResponse = await fetch(SCHIFT_LLM_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${process.env.SCHIFT_API_KEY}`,
+    },
+    body: JSON.stringify({
+      model: 'gpt-4o-mini',
+      messages,
+      temperature: 0.3,  // lower temp for factual Q&A
+    }),
+  });
+
+  const llmData = await llmResponse.json<{
+    choices: Array<{ message: { content: string } }>;
+  }>();
+  const assistantMessage = llmData.choices[0].message.content;
+
+  // 6. Store this turn in session history
+  history.push({ role: 'user', content: message });
+  history.push({ role: 'assistant', content: assistantMessage });
+  sessions.set(sessionId, history);
+
+  return c.json({
+    response: assistantMessage,
+    sources: results.map(r => ({ id: r.id, score: r.score })),
+  });
+});
+
+// Clear session on explicit reset
+app.delete('/api/chat/:sessionId', (c) => {
+  sessions.delete(c.req.param('sessionId'));
+  return c.json({ cleared: true });
+});
+
+export default app;
+```
+
+**Python (FastAPI) alternative:**
+
+```python
+# main.py — FastAPI equivalent
+from fastapi import FastAPI
+from pydantic import BaseModel
+from schift import Schift
+import httpx, os
+
+app = FastAPI()
+client = Schift(api_key=os.environ["SCHIFT_API_KEY"])
+
+# In-memory store; swap for Redis in production
+sessions: dict[str, list[dict]] = {}
+
+COLLECTION_ID = "col_your_collection"
+SCHIFT_LLM_URL = "https://api.schift.io/v1/llm/chat/completions"
+
+class ChatRequest(BaseModel):
+    message: str
+    session_id: str
+
+@app.post("/api/chat")
+async def chat(body: ChatRequest):
+    history = sessions.setdefault(body.session_id, [])
+
+    # Build search query from recent conversation context
+    recent = " ".join(m["content"] for m in history[-4:])
+    search_query = f"{recent} {body.message}".strip()
+
+    # Retrieve from Schift
+    results = client.search(
+        COLLECTION_ID, search_query, top_k=4, score_threshold=0.70
+    )
+    context = "\n\n".join(r.text for r in results)
+
+    # Assemble messages
+    messages = [
+        {
+            "role": "system",
+            "content": f"Answer based on context. Be honest if unsure.\n\n## Context\n{context or '(none)'}",
+        },
+        *history[-10:],
+        {"role": "user", "content": body.message},
+    ]
+
+    # Call Schift's LLM proxy (OpenAI-compatible)
+    async with httpx.AsyncClient() as http:
+        resp = await http.post(
+            SCHIFT_LLM_URL,
+            headers={"Authorization": f"Bearer {os.environ['SCHIFT_API_KEY']}"},
+            json={"model": "gpt-4o-mini", "messages": messages, "temperature": 0.3},
+        )
+    data = resp.json()
+    answer = data["choices"][0]["message"]["content"]
+
+    # Save turn
+    history.append({"role": "user", "content": body.message})
+    history.append({"role": "assistant", "content": answer})
+
+    return {"response": answer, "sources": [{"id": r.id, "score": r.score} for r in results]}
+```
+
+**Production considerations:**
+
+- Replace the in-memory `sessions` map with Redis (`ioredis` / `redis-py`) keyed by session ID with a TTL (e.g. 30 minutes)
+- Cap `trimmedHistory` at 10 turns to keep the prompt within model context limits
+- Use a lower `temperature` (0.1–0.4) for factual chatbots; higher (0.6–0.8) for creative assistants
+- Schift's `/v1/llm/chat/completions` proxy accepts the same request format as OpenAI — you can swap models by changing the `model` field without changing any other code
+
+## Reference
+
+- https://docs.schift.io/llm/chat-completions
+- https://docs.schift.io/search/overview

schift_cli/data/schift-best-practices/references/cost-batching.md

@@ -0,0 +1,179 @@
+---
+title: Batch API Calls to Minimize Per-Call Overhead and Cost
+impact: MEDIUM
+impactDescription: Each individual API call is billed as 1 unit regardless of how many texts it contains (up to 100). Sending 1000 single-text calls costs 100x more than sending 10 batches of 100 texts. Batching is the single highest-leverage cost optimization.
+tags:
+  - cost
+  - batching
+  - embed
+  - performance
+  - throughput
+---
+
+## Batch API Calls to Minimize Per-Call Overhead and Cost
+
+Schift billing is per API call, not per text. One call can embed up to 100 texts — and it costs exactly the same as one call embedding a single text. This means that how you structure your calls matters far more than how much text you send.
+
+The rule is simple: never make one API call per document. Always accumulate texts into batches of up to 100 and call `embed_batch` / `embedBatch` once per batch.
+
+**Billing unit**: 1 API call = 1 billing unit = $0.10 per 1,000 calls, regardless of batch size (up to 100 items per call).
+
+### Incorrect
+
+One embed call per text — 1000 texts = 1000 API calls = $0.10:
+
+```python
+# Python — one call per document: 1000 texts = 1000 API calls = $0.10
+from schift import Schift
+
+client = Schift(api_key="sch_...")
+
+documents = load_documents()  # 1000 documents
+
+# Every call is 1 billing unit — this is 1000 billing units
+for doc in documents:
+    embedding = client.embed(doc.text)  # 1 call per doc
+    store_embedding(doc.id, embedding)
+
+# Cost: 1000 calls × ($0.10 / 1000 calls) = $0.10
+# Latency: 1000 sequential round trips (or N parallel, but N connections)
+```
+
+```typescript
+// TypeScript — same problem: one call per document
+import { Schift } from '@schift-io/sdk';
+
+const client = new Schift({ apiKey: 'sch_...' });
+
+const documents = await loadDocuments();  // 1000 documents
+
+// Sequential: slow and wasteful
+for (const doc of documents) {
+  const embedding = await client.embed(doc.text);  // 1 billing unit each
+  await storeEmbedding(doc.id, embedding);
+}
+
+// Even with Promise.all, still 1000 separate API calls:
+const embeddings = await Promise.all(
+  documents.map(doc => client.embed(doc.text))  // still 1000 calls
+);
+// Cost: 1000 billing units = $0.10
+```
+
+### Correct
+
+Batch up to 100 texts per call — 1000 texts = 10 API calls = $0.001:
+
+```python
+# Python — batch embedding: 1000 texts in 10 calls = 10 billing units = $0.001
+from schift import Schift
+
+client = Schift(api_key="sch_...")
+
+documents = load_documents()  # 1000 documents
+BATCH_SIZE = 100  # max 100 per call
+
+# Chunk documents into batches of 100
+batches = [documents[i:i+BATCH_SIZE] for i in range(0, len(documents), BATCH_SIZE)]
+
+for batch in batches:
+    texts = [doc.text for doc in batch]
+    embeddings = client.embed_batch(texts)  # 1 call for up to 100 texts
+
+    for doc, embedding in zip(batch, embeddings):
+        store_embedding(doc.id, embedding)
+
+# Cost: 10 calls × ($0.10 / 1000 calls) = $0.001  (100x cheaper)
+# Throughput: 10 round trips vs 1000
+```
+
+```typescript
+// TypeScript — batch embedding: 100x cost reduction
+import { Schift } from '@schift-io/sdk';
+
+const client = new Schift({ apiKey: 'sch_...' });
+
+const documents = await loadDocuments();  // 1000 documents
+const BATCH_SIZE = 100;
+
+// Helper: split array into chunks
+function chunk<T>(arr: T[], size: number): T[][] {
+  return Array.from({ length: Math.ceil(arr.length / size) }, (_, i) =>
+    arr.slice(i * size, i * size + size)
+  );
+}
+
+const batches = chunk(documents, BATCH_SIZE);
+
+for (const batch of batches) {
+  const texts = batch.map(doc => doc.text);
+  const embeddings = await client.embedBatch(texts);  // 1 call for up to 100 texts
+
+  await Promise.all(
+    batch.map((doc, i) => storeEmbedding(doc.id, embeddings[i]))
+  );
+}
+
+// Cost: 10 billing units = $0.001  (vs $0.10 for individual calls)
+```
+
+**Cost comparison at scale:**
+
+| Approach | 1K texts | 10K texts | 100K texts |
+|----------|----------|-----------|------------|
+| 1 call per text | $0.10 | $1.00 | $10.00 |
+| Batch of 100 | $0.001 | $0.01 | $0.10 |
+| **Savings** | **99%** | **99%** | **99%** |
+
+Also cache embeddings client-side for repeated queries to avoid redundant API calls entirely:
+
+```python
+# Python — client-side embedding cache for repeated queries
+import hashlib
+from functools import lru_cache
+from schift import Schift
+
+client = Schift(api_key="sch_...")
+
+# Simple in-memory cache (use Redis or a file cache for persistence)
+_embedding_cache: dict[str, list[float]] = {}
+
+def embed_with_cache(text: str) -> list[float]:
+    key = hashlib.sha256(text.encode()).hexdigest()
+    if key not in _embedding_cache:
+        _embedding_cache[key] = client.embed(text)
+    return _embedding_cache[key]
+
+# For search queries that repeat across users (e.g., "what is your refund policy?"),
+# this means the embedding is computed once and reused for all matching queries.
+```
+
+```typescript
+// TypeScript — client-side embedding cache
+import { createHash } from 'crypto';
+import { Schift } from '@schift-io/sdk';
+
+const client = new Schift({ apiKey: 'sch_...' });
+const cache = new Map<string, number[]>();
+
+async function embedWithCache(text: string): Promise<number[]> {
+  const key = createHash('sha256').update(text).digest('hex');
+  if (!cache.has(key)) {
+    cache.set(key, await client.embed(text));
+  }
+  return cache.get(key)!;
+}
+// Use a TTL cache (e.g., lru-cache with maxAge) for production.
+```
+
+**Batching checklist:**
+
+- Use `embed_batch` / `embedBatch` for all bulk operations (indexing, re-indexing, data migration)
+- Use `embed` only for single real-time queries (user search input)
+- Cache query embeddings when the same query may repeat (chatbot, search UI)
+- For very large datasets (>100K texts), process batches concurrently with a concurrency limit of 5–10
+
+## Reference
+
+- https://docs.schift.io/api/embed-batch
+- https://docs.schift.io/pricing