schift-cli 0.1.0__py3-none-any.whl

schift_cli/commands/query.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import click
+
+from schift_cli.client import get_client, SchiftAPIError
+from schift_cli.display import console, error, print_table
+
+
+@click.command("query")
+@click.argument("text")
+@click.option("--collection", "-c", required=True, help="Collection name to search")
+@click.option("--top-k", "-k", type=int, default=10, show_default=True,
+              help="Number of results to return")
+@click.option("--model", "-m", default=None, help="Embedding model to use for the query (uses collection default if omitted)")
+@click.option("--threshold", type=float, default=None, help="Minimum similarity score filter")
+def query(text: str, collection: str, top_k: int, model: str | None, threshold: float | None) -> None:
+    """Search a vector collection with natural language.
+
+    TEXT is the search query string.
+    """
+    payload: dict = {
+        "text": text,
+        "collection": collection,
+        "top_k": top_k,
+    }
+    if model:
+        payload["model"] = model
+    if threshold is not None:
+        payload["threshold"] = threshold
+
+    try:
+        with get_client() as client:
+            data = client.post("/query", json=payload)
+    except SchiftAPIError as e:
+        error(f"Query failed: {e.detail}")
+        raise SystemExit(1)
+    except click.ClickException:
+        raise
+
+    results = data.get("results", [])
+    if not results:
+        console.print("No results found.")
+        return
+
+    rows = [
+        (
+            str(i + 1),
+            r.get("id", "-"),
+            f"{r.get('score', 0):.4f}",
+            _truncate(r.get("text", r.get("metadata", {}).get("text", "-")), 80),
+        )
+        for i, r in enumerate(results)
+    ]
+
+    print_table(
+        f"Search Results ({collection})",
+        ["#", "ID", "Score", "Text"],
+        rows,
+        caption=f"Query: \"{text}\" | top-k: {top_k}",
+    )
+
+
+def _truncate(s: str, max_len: int) -> str:
+    if len(s) <= max_len:
+        return s
+    return s[: max_len - 3] + "..."

schift_cli/commands/skill.py

@@ -0,0 +1,110 @@
+"""schift skill install — install Claude Code skills for Schift best practices."""
+
+from __future__ import annotations
+
+import shutil
+from importlib import resources
+from pathlib import Path
+
+import click
+
+
+SKILL_NAME = "schift-best-practices"
+CLAUDE_SKILLS_DIR = Path.home() / ".claude" / "skills"
+
+
+@click.group()
+def skill() -> None:
+    """Manage Claude Code skills for Schift."""
+
+
+@skill.command()
+@click.option(
+    "--dest",
+    type=click.Path(),
+    default=None,
+    help="Override destination directory (default: ~/.claude/skills/)",
+)
+def install(dest: str | None) -> None:
+    """Install schift-best-practices skill for Claude Code."""
+
+    target = Path(dest) if dest else CLAUDE_SKILLS_DIR / SKILL_NAME
+
+    # Locate bundled skill files
+    source = _find_skill_source()
+    if source is None:
+        click.secho(
+            "Error: bundled skill files not found. "
+            "Try reinstalling schift-cli.",
+            fg="red",
+        )
+        raise SystemExit(1)
+
+    if target.exists():
+        click.confirm(
+            f"{target} already exists. Overwrite?",
+            abort=True,
+        )
+        shutil.rmtree(target)
+
+    shutil.copytree(source, target)
+
+    # Create CLAUDE.md symlink if missing
+    claude_md = target / "CLAUDE.md"
+    agents_md = target / "AGENTS.md"
+    if agents_md.exists() and not claude_md.exists():
+        claude_md.symlink_to("AGENTS.md")
+
+    click.secho(f"Installed {SKILL_NAME} to {target}", fg="green")
+    click.echo(
+        "Claude Code will now reference Schift best practices "
+        "when you work on embedding, search, or RAG code."
+    )
+
+
+@skill.command()
+def uninstall() -> None:
+    """Remove schift-best-practices skill from Claude Code."""
+
+    target = CLAUDE_SKILLS_DIR / SKILL_NAME
+    if not target.exists():
+        click.echo(f"{SKILL_NAME} is not installed.")
+        return
+
+    click.confirm(f"Remove {target}?", abort=True)
+    shutil.rmtree(target)
+    click.secho(f"Removed {SKILL_NAME}", fg="yellow")
+
+
+@skill.command(name="list")
+def list_skills() -> None:
+    """List installed Schift skills."""
+
+    target = CLAUDE_SKILLS_DIR / SKILL_NAME
+    if target.exists():
+        refs = list((target / "references").glob("*.md")) if (target / "references").exists() else []
+        click.echo(f"{SKILL_NAME}  ({len(refs)} references)  {target}")
+    else:
+        click.echo("No Schift skills installed. Run: schift skill install")
+
+
+def _find_skill_source() -> Path | None:
+    """Locate the bundled skill directory shipped with the package."""
+
+    # 1. Check package data (installed via pip)
+    try:
+        pkg = resources.files("schift_cli") / "data" / SKILL_NAME
+        # resources.files returns a Traversable; resolve to Path
+        pkg_path = Path(str(pkg))
+        if pkg_path.is_dir() and (pkg_path / "SKILL.md").exists():
+            return pkg_path
+    except (TypeError, FileNotFoundError):
+        pass
+
+    # 2. Fallback: check relative to repo root (dev mode / editable install)
+    repo_root = Path(__file__).resolve().parents[4]  # sdk/cli/schift_cli/commands → repo root
+    dev_path = repo_root / "skills" / SKILL_NAME
+    if dev_path.is_dir() and (dev_path / "SKILL.md").exists():
+        return dev_path
+
+    return None

schift_cli/commands/usage.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import click
+
+from schift_cli.client import get_client, SchiftAPIError
+from schift_cli.display import error, print_kv, print_table
+
+
+@click.command("usage")
+@click.option("--period", "-p", default="30d", show_default=True,
+              help="Time period (e.g. 7d, 30d, 90d)")
+def usage(period: str) -> None:
+    """Show API usage and billing summary."""
+    try:
+        with get_client() as client:
+            data = client.get("/usage", params={"period": period})
+    except SchiftAPIError as e:
+        error(f"Failed to fetch usage: {e.detail}")
+        raise SystemExit(1)
+    except click.ClickException:
+        raise
+
+    summary = data.get("summary", data)
+
+    print_kv(f"Usage Summary (last {period})", {
+        "Total Requests": summary.get("total_requests", "-"),
+        "Embeddings Generated": summary.get("embeddings_generated", "-"),
+        "Projections Computed": summary.get("projections_computed", "-"),
+        "Queries Executed": summary.get("queries_executed", "-"),
+        "Storage Used": summary.get("storage_used", "-"),
+        "Cost": summary.get("cost", "-"),
+    })
+
+    # Show per-model breakdown if available
+    breakdown = data.get("by_model", [])
+    if breakdown:
+        rows = [
+            (
+                b.get("model", ""),
+                str(b.get("requests", "")),
+                str(b.get("tokens", "")),
+                b.get("cost", ""),
+            )
+            for b in breakdown
+        ]
+        print_table(
+            "Usage by Model",
+            ["Model", "Requests", "Tokens", "Cost"],
+            rows,
+        )

schift_cli/config.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+CONFIG_DIR = Path.home() / ".schift"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+ENV_API_KEY = "SCHIFT_API_KEY"
+ENV_API_URL = "SCHIFT_API_URL"
+
+DEFAULT_API_URL = "https://api.schift.io/v1"
+
+
+def _ensure_config_dir() -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def load_config() -> dict[str, Any]:
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        return json.loads(CONFIG_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_config(config: dict[str, Any]) -> None:
+    _ensure_config_dir()
+    CONFIG_FILE.write_text(json.dumps(config, indent=2) + "\n")
+    # Restrict permissions — API key lives here
+    CONFIG_FILE.chmod(0o600)
+
+
+def get_api_key() -> str | None:
+    """Return API key from env var (highest priority) or config file."""
+    env_key = os.environ.get(ENV_API_KEY)
+    if env_key:
+        return env_key
+    return load_config().get("api_key")
+
+
+def set_api_key(api_key: str) -> None:
+    config = load_config()
+    config["api_key"] = api_key
+    save_config(config)
+
+
+def clear_api_key() -> None:
+    config = load_config()
+    config.pop("api_key", None)
+    save_config(config)
+
+
+def get_api_url() -> str:
+    return os.environ.get(ENV_API_URL, DEFAULT_API_URL)

schift_cli/data/schift-best-practices/AGENTS.md

@@ -0,0 +1,77 @@
+# schift-best-practices
+
+> **Note:** `CLAUDE.md` is a symlink to this file.
+
+## Overview
+
+Embedding API, vector search, and RAG pipeline best practices from Schift. Use this skill when building embedding-powered applications, integrating Schift SDK, or optimizing vector search and retrieval.
+
+## Structure
+
+```
+schift-best-practices/
+  SKILL.md       # Main skill file - read this first
+  AGENTS.md      # This navigation guide
+  CLAUDE.md      # Symlink to AGENTS.md
+  references/    # Detailed reference files
+```
+
+## Usage
+
+1. Read `SKILL.md` for the main skill instructions
+2. Browse `references/` for detailed documentation on specific topics
+3. Reference files are loaded on-demand - read only what you need
+
+## Reference Categories
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Embedding API | CRITICAL | `embed-` |
+| 2 | Search & Retrieval | CRITICAL | `search-` |
+| 3 | Authentication & SDK | CRITICAL | `sdk-` |
+| 4 | Bucket Management | HIGH | `bucket-` |
+| 5 | RAG Pipelines | HIGH | `rag-` |
+| 6 | Cost Optimization | MEDIUM | `cost-` |
+| 7 | Deployment | LOW-MEDIUM | `deploy-` |
+| 8 | Chatbot Patterns | LOW | `chatbot-` |
+
+Reference files are named `{prefix}-{topic}.md` (e.g., `embed-batch-processing.md`).
+
+## Available References
+
+**Embedding API** (`embed-`):
+- `references/embed-batch-processing.md`
+- `references/embed-multimodal.md`
+- `references/embed-task-types.md`
+- `references/embed-error-handling.md`
+
+**Search & Retrieval** (`search-`):
+- `references/search-similarity-tuning.md`
+- `references/search-hybrid.md`
+- `references/search-collection-design.md`
+
+**Authentication & SDK** (`sdk-`):
+- `references/sdk-auth-patterns.md`
+- `references/sdk-async-patterns.md`
+
+**Bucket Management** (`bucket-`):
+- `references/bucket-upload.md`
+- `references/bucket-organization.md`
+
+**RAG Pipelines** (`rag-`):
+- `references/rag-chunking.md`
+- `references/rag-workflow-builder.md`
+
+**Cost Optimization** (`cost-`):
+- `references/cost-batching.md`
+- `references/cost-storage-tiers.md`
+
+**Deployment** (`deploy-`):
+- `references/deploy-cloudrun.md`
+
+**Chatbot Patterns** (`chatbot-`):
+- `references/chatbot-widget.md`
+
+---
+
+*18 reference files across 8 categories*

schift_cli/data/schift-best-practices/CLAUDE.md

@@ -0,0 +1,77 @@
+# schift-best-practices
+
+> **Note:** `CLAUDE.md` is a symlink to this file.
+
+## Overview
+
+Embedding API, vector search, and RAG pipeline best practices from Schift. Use this skill when building embedding-powered applications, integrating Schift SDK, or optimizing vector search and retrieval.
+
+## Structure
+
+```
+schift-best-practices/
+  SKILL.md       # Main skill file - read this first
+  AGENTS.md      # This navigation guide
+  CLAUDE.md      # Symlink to AGENTS.md
+  references/    # Detailed reference files
+```
+
+## Usage
+
+1. Read `SKILL.md` for the main skill instructions
+2. Browse `references/` for detailed documentation on specific topics
+3. Reference files are loaded on-demand - read only what you need
+
+## Reference Categories
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Embedding API | CRITICAL | `embed-` |
+| 2 | Search & Retrieval | CRITICAL | `search-` |
+| 3 | Authentication & SDK | CRITICAL | `sdk-` |
+| 4 | Bucket Management | HIGH | `bucket-` |
+| 5 | RAG Pipelines | HIGH | `rag-` |
+| 6 | Cost Optimization | MEDIUM | `cost-` |
+| 7 | Deployment | LOW-MEDIUM | `deploy-` |
+| 8 | Chatbot Patterns | LOW | `chatbot-` |
+
+Reference files are named `{prefix}-{topic}.md` (e.g., `embed-batch-processing.md`).
+
+## Available References
+
+**Embedding API** (`embed-`):
+- `references/embed-batch-processing.md`
+- `references/embed-multimodal.md`
+- `references/embed-task-types.md`
+- `references/embed-error-handling.md`
+
+**Search & Retrieval** (`search-`):
+- `references/search-similarity-tuning.md`
+- `references/search-hybrid.md`
+- `references/search-collection-design.md`
+
+**Authentication & SDK** (`sdk-`):
+- `references/sdk-auth-patterns.md`
+- `references/sdk-async-patterns.md`
+
+**Bucket Management** (`bucket-`):
+- `references/bucket-upload.md`
+- `references/bucket-organization.md`
+
+**RAG Pipelines** (`rag-`):
+- `references/rag-chunking.md`
+- `references/rag-workflow-builder.md`
+
+**Cost Optimization** (`cost-`):
+- `references/cost-batching.md`
+- `references/cost-storage-tiers.md`
+
+**Deployment** (`deploy-`):
+- `references/deploy-cloudrun.md`
+
+**Chatbot Patterns** (`chatbot-`):
+- `references/chatbot-widget.md`
+
+---
+
+*18 reference files across 8 categories*

schift_cli/data/schift-best-practices/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: schift-best-practices
+description: Embedding API, vector search, and RAG pipeline best practices from Schift. Use this skill when building embedding-powered applications, integrating Schift SDK, or optimizing vector search and retrieval.
+license: MIT
+metadata:
+  author: schift
+  version: "0.1.0"
+  organization: Schift
+  date: March 2026
+  abstract: Comprehensive embedding and vector search best practices for developers using Schift's managed embedding infrastructure. Contains rules across 8 categories covering embedding API usage, search optimization, bucket management, RAG pipelines, SDK patterns, cost optimization, deployment, and chatbot integration. Each rule includes incorrect vs. correct code examples in Python and TypeScript.
+---
+
+# Schift Best Practices
+
+Best practices for building embedding-powered applications with Schift's managed embedding infrastructure. Covers embedding API, vector search, RAG pipelines, and deployment patterns.
+
+## When to Apply
+
+Reference these guidelines when:
+- Calling Schift's embedding or search API
+- Designing vector collections or bucket structures
+- Building RAG pipelines with the workflow engine
+- Integrating the Python or TypeScript SDK
+- Deploying Schift-powered applications
+- Optimizing cost and performance for embedding workloads
+- Building chatbot or Q&A interfaces backed by Schift
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Embedding API | CRITICAL | `embed-` |
+| 2 | Search & Retrieval | CRITICAL | `search-` |
+| 3 | Authentication & SDK | CRITICAL | `sdk-` |
+| 4 | Bucket Management | HIGH | `bucket-` |
+| 5 | RAG Pipelines | HIGH | `rag-` |
+| 6 | Cost Optimization | MEDIUM | `cost-` |
+| 7 | Deployment | LOW-MEDIUM | `deploy-` |
+| 8 | Chatbot Patterns | LOW | `chatbot-` |
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+references/embed-batch-processing.md
+references/search-similarity-tuning.md
+references/sdk-auth-patterns.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Performance impact or cost implications
+- Schift-specific notes
+
+## Key Concepts
+
+- **Canonical Space**: All embeddings are projected into Schift's 1024-dimensional canonical vector space, enabling cross-model compatibility
+- **Bucket**: File upload → automatic OCR + chunking + embedding → searchable index
+- **Workflow**: DAG-based RAG pipeline builder with block nodes
+- **Task Types**: retrieval, similarity, classification, clustering, QA, fact_verification, code_retrieval
+- **Modalities**: text, image, audio, video, document
+
+## SDK Quick Start
+
+```python
+# Python
+pip install schift
+from schift import Schift
+client = Schift(api_key="sch_...")
+result = client.embed("Hello world")
+```
+
+```typescript
+// TypeScript
+npm install @schift-io/sdk
+import { Schift } from '@schift-io/sdk';
+const client = new Schift({ apiKey: 'sch_...' });
+const result = await client.embed('Hello world');
+```
+
+## References
+
+- https://docs.schift.io
+- https://github.com/schift-io/schift
+- https://pypi.org/project/schift/
+- https://www.npmjs.com/package/@schift-io/sdk

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

@@ -0,0 +1,126 @@
+---
+title: Bucket Organization by Data Domain
+impact: MEDIUM
+impactDescription: One bucket per upload session inflates bucket count, fragments the FAISS index, and makes cross-document search impossible without aggregating results manually. Long-lived domain buckets give better search quality and simpler code.
+tags: [bucket, organization, architecture, faiss, search]
+---
+
+## Organize Buckets by Data Domain, Not by Upload Session
+
+A Schift bucket maintains a single FAISS index over all documents ever uploaded to it. Search over a bucket queries that entire index in one call. When you create a new bucket for every upload session, each bucket becomes a silo — you lose the ability to search across related documents without fanning out to every bucket and merging results yourself.
+
+Design buckets around stable data domains: what set of documents belongs together conceptually? That set is a bucket.
+
+### Incorrect
+
+```python
+# Python - new bucket per upload session
+# After 10 uploads you have 10 buckets, none searchable together
+from schift import Schift
+from datetime import datetime
+
+client = Schift()
+
+def upload_weekly_reports(files: list[str]):
+    # Creates a new bucket every time this function runs
+    bucket = client.bucket.create(f"reports-{datetime.now().isoformat()}")
+    job = client.bucket.upload(bucket.id, files=files)
+    job.wait()
+    return bucket.id
+
+# Searching now requires querying every bucket and merging manually
+def search_all_reports(query: str) -> list:
+    buckets = client.bucket.list()  # grows every week
+    all_hits = []
+    for b in buckets:
+        results = client.bucket.search(b.id, query)
+        all_hits.extend(results.hits)
+    all_hits.sort(key=lambda h: h.score, reverse=True)
+    return all_hits
+```
+
+```typescript
+// TypeScript - same anti-pattern
+import { Schift } from '@schift-io/sdk';
+
+const client = new Schift();
+
+async function uploadWeeklyReports(files: string[]) {
+  const bucket = await client.bucket.create(`reports-${Date.now()}`);
+  const job = await client.bucket.upload(bucket.id, { files });
+  await job.wait();
+  return bucket.id;
+}
+```
+
+### Correct
+
+```python
+# Python - one bucket per data domain, append files over time
+from schift import Schift
+
+client = Schift()
+
+# Provision once (e.g., at app startup or in a migration script)
+def get_or_create_bucket(name: str) -> str:
+    existing = [b for b in client.bucket.list() if b.name == name]
+    if existing:
+        return existing[0].id
+    return client.bucket.create(name).id
+
+# Reuse the same bucket across all weekly uploads
+REPORTS_BUCKET = get_or_create_bucket("weekly-reports")
+
+def upload_weekly_reports(files: list[str]):
+    job = client.bucket.upload(REPORTS_BUCKET, files=files)
+    job.wait()
+
+# Single search call covers all documents ever uploaded to this bucket
+def search_reports(query: str):
+    return client.bucket.search(REPORTS_BUCKET, query).hits
+```
+
+```typescript
+// TypeScript - same domain-first approach
+import { Schift } from '@schift-io/sdk';
+
+const client = new Schift();
+
+async function getOrCreateBucket(name: string): Promise<string> {
+  const buckets = await client.bucket.list();
+  const existing = buckets.find(b => b.name === name);
+  if (existing) return existing.id;
+  const bucket = await client.bucket.create(name);
+  return bucket.id;
+}
+
+const REPORTS_BUCKET = await getOrCreateBucket('weekly-reports');
+
+async function uploadWeeklyReports(files: string[]) {
+  const job = await client.bucket.upload(REPORTS_BUCKET, { files });
+  await job.wait();
+}
+
+async function searchReports(query: string) {
+  return (await client.bucket.search(REPORTS_BUCKET, query)).hits;
+}
+```
+
+**Recommended domain examples:**
+
+| Domain | Bucket name |
+|--------|-------------|
+| Internal knowledge base | `company-docs` |
+| Product documentation | `product-manuals` |
+| Legal contracts | `legal-contracts` |
+| Support ticket history | `support-history` |
+| Weekly reports | `weekly-reports` |
+
+If two domains are always searched together, merge them into one bucket. If they are never searched together and have different access control requirements, keep them separate.
+
+Each bucket has an independent FAISS index. Uploads append to the index; the index is never rebuilt from scratch unless explicitly requested.
+
+## Reference
+
+- https://docs.schift.io/buckets/organization
+- https://docs.schift.io/buckets/faiss-index