EvoScientist 0.1.0rc1__py3-none-any.whl → 0.1.0rc2__py3-none-any.whl

EvoScientist/skills/clip/references/applications.md

@@ -0,0 +1,207 @@
+# CLIP Applications Guide
+
+Practical applications and use cases for CLIP.
+
+## Zero-shot image classification
+
+```python
+import torch
+import clip
+from PIL import Image
+
+model, preprocess = clip.load("ViT-B/32")
+
+# Define categories
+categories = [
+    "a photo of a dog",
+    "a photo of a cat",
+    "a photo of a bird",
+    "a photo of a car",
+    "a photo of a person"
+]
+
+# Prepare image
+image = preprocess(Image.open("photo.jpg")).unsqueeze(0)
+text = clip.tokenize(categories)
+
+# Classify
+with torch.no_grad():
+    image_features = model.encode_image(image)
+    text_features = model.encode_text(text)
+
+    logits_per_image, _ = model(image, text)
+    probs = logits_per_image.softmax(dim=-1).cpu().numpy()
+
+# Print results
+for category, prob in zip(categories, probs[0]):
+    print(f"{category}: {prob:.2%}")
+```
+
+## Semantic image search
+
+```python
+# Index images
+image_database = []
+image_paths = ["img1.jpg", "img2.jpg", "img3.jpg"]
+
+for img_path in image_paths:
+    image = preprocess(Image.open(img_path)).unsqueeze(0)
+    with torch.no_grad():
+        features = model.encode_image(image)
+        features /= features.norm(dim=-1, keepdim=True)
+    image_database.append((img_path, features))
+
+# Search with text
+query = "a sunset over mountains"
+text_input = clip.tokenize([query])
+
+with torch.no_grad():
+    text_features = model.encode_text(text_input)
+    text_features /= text_features.norm(dim=-1, keepdim=True)
+
+# Find matches
+similarities = []
+for img_path, img_features in image_database:
+    similarity = (text_features @ img_features.T).item()
+    similarities.append((img_path, similarity))
+
+# Sort by similarity
+similarities.sort(key=lambda x: x[1], reverse=True)
+for img_path, score in similarities[:3]:
+    print(f"{img_path}: {score:.3f}")
+```
+
+## Content moderation
+
+```python
+# Define safety categories
+categories = [
+    "safe for work content",
+    "not safe for work content",
+    "violent or graphic content",
+    "hate speech or offensive content",
+    "spam or misleading content"
+]
+
+text = clip.tokenize(categories)
+
+# Check image
+with torch.no_grad():
+    logits, _ = model(image, text)
+    probs = logits.softmax(dim=-1)
+
+# Get classification
+max_idx = probs.argmax().item()
+confidence = probs[0, max_idx].item()
+
+if confidence > 0.7:
+    print(f"Classified as: {categories[max_idx]} ({confidence:.2%})")
+else:
+    print(f"Uncertain classification (confidence: {confidence:.2%})")
+```
+
+## Image-to-text retrieval
+
+```python
+# Text database
+captions = [
+    "A beautiful sunset over the ocean",
+    "A cute dog playing in the park",
+    "A modern city skyline at night",
+    "A delicious pizza with toppings"
+]
+
+# Encode captions
+caption_features = []
+for caption in captions:
+    text = clip.tokenize([caption])
+    with torch.no_grad():
+        features = model.encode_text(text)
+        features /= features.norm(dim=-1, keepdim=True)
+    caption_features.append(features)
+
+caption_features = torch.cat(caption_features)
+
+# Find matching captions for image
+with torch.no_grad():
+    image_features = model.encode_image(image)
+    image_features /= image_features.norm(dim=-1, keepdim=True)
+
+similarities = (image_features @ caption_features.T).squeeze(0)
+top_k = similarities.topk(3)
+
+for idx, score in zip(top_k.indices, top_k.values):
+    print(f"{captions[idx]}: {score:.3f}")
+```
+
+## Visual question answering
+
+```python
+# Create yes/no questions
+image = preprocess(Image.open("photo.jpg")).unsqueeze(0)
+
+questions = [
+    "a photo showing people",
+    "a photo showing animals",
+    "a photo taken indoors",
+    "a photo taken outdoors",
+    "a photo taken during daytime",
+    "a photo taken at night"
+]
+
+text = clip.tokenize(questions)
+
+with torch.no_grad():
+    logits, _ = model(image, text)
+    probs = logits.softmax(dim=-1)
+
+# Answer questions
+for question, prob in zip(questions, probs[0]):
+    answer = "Yes" if prob > 0.5 else "No"
+    print(f"{question}: {answer} ({prob:.2%})")
+```
+
+## Image deduplication
+
+```python
+# Detect duplicate/similar images
+def compute_similarity(img1_path, img2_path):
+    img1 = preprocess(Image.open(img1_path)).unsqueeze(0)
+    img2 = preprocess(Image.open(img2_path)).unsqueeze(0)
+
+    with torch.no_grad():
+        feat1 = model.encode_image(img1)
+        feat2 = model.encode_image(img2)
+
+        feat1 /= feat1.norm(dim=-1, keepdim=True)
+        feat2 /= feat2.norm(dim=-1, keepdim=True)
+
+        similarity = (feat1 @ feat2.T).item()
+
+    return similarity
+
+# Check for duplicates
+threshold = 0.95
+image_pairs = [("img1.jpg", "img2.jpg"), ("img1.jpg", "img3.jpg")]
+
+for img1, img2 in image_pairs:
+    sim = compute_similarity(img1, img2)
+    if sim > threshold:
+        print(f"{img1} and {img2} are duplicates (similarity: {sim:.3f})")
+```
+
+## Best practices
+
+1. **Use descriptive labels** - "a photo of X" works better than just "X"
+2. **Normalize embeddings** - Always normalize for cosine similarity
+3. **Batch processing** - Process multiple images/texts together
+4. **Cache embeddings** - Expensive to recompute
+5. **Set appropriate thresholds** - Test on validation data
+6. **Use GPU** - 10-50× faster than CPU
+7. **Consider model size** - ViT-B/32 good default, ViT-L/14 for best quality
+
+## Resources
+
+- **Paper**: https://arxiv.org/abs/2103.00020
+- **GitHub**: https://github.com/openai/CLIP
+- **Colab**: https://colab.research.google.com/github/openai/clip/

EvoScientist/skills/find-skills/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", or express interest in extending capabilities. Uses a non-interactive installer script suitable for automated agents.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Wants to search for tools, templates, or workflows
+- Expresses interest in extending agent capabilities
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## Step 1: Search for Skills
+
+Use `npx -y skills find` with a relevant keyword to search the ecosystem:
+
+```bash
+npx -y skills find [query]
+```
+
+Examples:
+- User asks "help me with React performance" → `npx -y skills find react performance`
+- User asks "is there a skill for PR reviews?" → `npx -y skills find pr review`
+- User asks "I need to create a changelog" → `npx -y skills find changelog`
+
+The search results will show installable skills like:
+
+```
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+Browse all available skills at: https://skills.sh/
+
+## Step 2: Present Options
+
+When you find relevant skills, present them to the user with:
+1. The skill name and what it does
+2. A link to learn more on skills.sh
+
+Ask the user which skill(s) they want to install. All skills are installed to `./skills/` in the current working directory.
+
+## Step 3: Install with the Script
+
+**IMPORTANT: Do NOT use `npx -y skills add` for installation** — it requires interactive prompts.
+
+Use the bundled installer script instead:
+
+```bash
+python /skills/find-skills/scripts/install_skill.py --url <github_url>
+```
+
+### Install Commands
+
+**From a GitHub URL** (most common — copy the URL from search results):
+```bash
+python /skills/find-skills/scripts/install_skill.py \
+  --url https://github.com/owner/repo/tree/main/skill-name
+```
+
+**From skills.sh shorthand** (owner/repo@skill):
+```bash
+python /skills/find-skills/scripts/install_skill.py \
+  --url vercel-labs/agent-skills@vercel-react-best-practices
+```
+
+**From repo + path** (install specific skills from a multi-skill repo):
+```bash
+# Single skill
+python /skills/find-skills/scripts/install_skill.py \
+  --repo owner/repo --path skill-name
+
+# Multiple skills from same repo
+python /skills/find-skills/scripts/install_skill.py \
+  --repo owner/repo --path skill-a --path skill-b
+```
+
+**With a specific git branch or tag**:
+```bash
+python /skills/find-skills/scripts/install_skill.py \
+  --repo owner/repo --path skill-name --ref v2.0
+```
+
+### Installer Options
+
+| Option | Description |
+|--------|-------------|
+| `--url` | GitHub URL or owner/repo@skill shorthand |
+| `--repo` | GitHub repo (owner/repo format) |
+| `--path` | Path to skill inside repo (repeatable) |
+| `--ref` | Git branch or tag |
+| `--dest` | Custom destination directory (default: `./skills`) |
+
+## Step 4: Confirm Installation
+
+After installation, verify by listing the skills directory:
+
+```bash
+ls /skills/   # all skills (system + user merged)
+```
+
+Then read the installed skill's SKILL.md to confirm it loaded correctly:
+
+```bash
+read_file /skills/<skill-name>/SKILL.md
+```
+
+## Common Skill Categories
+
+| Category | Example Queries |
+|----------|----------------|
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing | testing, jest, playwright, e2e |
+| DevOps | deploy, docker, kubernetes, ci-cd |
+| Documentation | docs, readme, changelog, api-docs |
+| Code Quality | review, lint, refactor, best-practices |
+| Design | ui, ux, design-system, accessibility |
+| Productivity | workflow, automation, git |
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Mention the user could create their own skill with `npx -y skills init`

EvoScientist/skills/find-skills/scripts/install_skill.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""Install a skill from GitHub into a local skills directory.
+
+Self-contained installer — no external dependencies beyond git.
+
+Usage examples:
+    # Install from a GitHub URL (auto-detects repo, ref, path)
+    python install_skill.py --url https://github.com/anthropics/skills/tree/main/excel
+
+    # Install from repo + path
+    python install_skill.py --repo anthropics/skills --path excel
+
+    # Install multiple skills from the same repo
+    python install_skill.py --repo anthropics/skills --path excel --path pdf
+
+    # Install with a specific git ref
+    python install_skill.py --repo org/repo --path my-skill --ref v2.0
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+
+def parse_github_url(url: str) -> tuple[str, str | None, str | None]:
+    """Parse a GitHub URL into (repo, ref, path).
+
+    Supports formats:
+        https://github.com/owner/repo
+        https://github.com/owner/repo/tree/main/path/to/skill
+        github.com/owner/repo/tree/branch/path
+        owner/repo@skill-name  (shorthand from skills.sh)
+
+    Returns:
+        (repo, ref_or_none, path_or_none)
+    """
+    # Shorthand: owner/repo@path
+    if "@" in url and "://" not in url:
+        repo, path = url.split("@", 1)
+        return repo.strip(), None, path.strip()
+
+    # Strip protocol and github.com prefix
+    cleaned = re.sub(r"^https?://", "", url)
+    cleaned = re.sub(r"^github\.com/", "", cleaned)
+    cleaned = cleaned.rstrip("/")
+
+    # Match: owner/repo/tree/ref/path...
+    m = re.match(r"^([^/]+/[^/]+)/tree/([^/]+)(?:/(.+))?$", cleaned)
+    if m:
+        return m.group(1), m.group(2), m.group(3)
+
+    # Match: owner/repo (no tree)
+    m = re.match(r"^([^/]+/[^/]+)$", cleaned)
+    if m:
+        return m.group(1), None, None
+
+    raise ValueError(f"Cannot parse GitHub URL: {url}")
+
+
+def clone_repo(repo: str, ref: str | None, dest: str) -> None:
+    """Shallow-clone a GitHub repo."""
+    clone_url = f"https://github.com/{repo}.git"
+    cmd = ["git", "clone", "--depth", "1"]
+    if ref:
+        cmd += ["--branch", ref]
+    cmd += [clone_url, dest]
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RuntimeError(f"git clone failed: {result.stderr.strip()}")
+
+
+def copy_skill(src: str, dest_dir: str) -> str:
+    """Copy a skill directory to the destination.
+
+    Returns:
+        The skill name (directory basename).
+    """
+    skill_name = os.path.basename(src.rstrip("/"))
+    target = os.path.join(dest_dir, skill_name)
+
+    if os.path.exists(target):
+        shutil.rmtree(target)
+        print(f"  Replaced existing: {skill_name}")
+
+    shutil.copytree(src, target)
+    return skill_name
+
+
+def validate_skill(path: str) -> bool:
+    """Check that a directory looks like a valid skill (has SKILL.md)."""
+    return os.path.isfile(os.path.join(path, "SKILL.md"))
+
+
+def install(
+    repo: str,
+    paths: list[str],
+    ref: str | None,
+    dest: str,
+) -> list[str]:
+    """Install skill(s) from a GitHub repo.
+
+    Returns:
+        List of installed skill names.
+    """
+    os.makedirs(dest, exist_ok=True)
+    installed: list[str] = []
+
+    with tempfile.TemporaryDirectory(prefix="skill-install-") as tmp:
+        clone_dir = os.path.join(tmp, "repo")
+        print(f"Cloning {repo}" + (f" @{ref}" if ref else "") + "...")
+        clone_repo(repo, ref, clone_dir)
+
+        if not paths:
+            # No path specified — treat entire repo as a single skill
+            if validate_skill(clone_dir):
+                name = copy_skill(clone_dir, dest)
+                installed.append(name)
+            else:
+                # List top-level directories that look like skills
+                for entry in sorted(os.listdir(clone_dir)):
+                    entry_path = os.path.join(clone_dir, entry)
+                    if os.path.isdir(entry_path) and validate_skill(entry_path):
+                        name = copy_skill(entry_path, dest)
+                        installed.append(name)
+
+                if not installed:
+                    print("No valid skills found in repository root.", file=sys.stderr)
+        else:
+            for p in paths:
+                skill_path = os.path.join(clone_dir, p.strip("/"))
+                if not os.path.isdir(skill_path):
+                    print(f"  Path not found: {p}", file=sys.stderr)
+                    continue
+                if not validate_skill(skill_path):
+                    print(f"  No SKILL.md in: {p}", file=sys.stderr)
+                    continue
+                name = copy_skill(skill_path, dest)
+                installed.append(name)
+
+    return installed
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Install skills from GitHub into a local skills directory.",
+    )
+    src = parser.add_mutually_exclusive_group(required=True)
+    src.add_argument(
+        "--url",
+        help="GitHub URL (e.g. https://github.com/owner/repo/tree/main/skill-name)",
+    )
+    src.add_argument(
+        "--repo",
+        help="GitHub repo (e.g. owner/repo)",
+    )
+    parser.add_argument(
+        "--path",
+        action="append",
+        default=[],
+        help="Path to skill inside repo (repeatable)",
+    )
+    parser.add_argument(
+        "--ref",
+        default=None,
+        help="Git branch or tag (default: repo default branch)",
+    )
+    parser.add_argument(
+        "--dest",
+        default="./skills",
+        help="Destination directory (default: ./skills)",
+    )
+
+    args = parser.parse_args()
+    dest = args.dest
+
+    # Parse source
+    if args.url:
+        repo, ref, path = parse_github_url(args.url)
+        ref = args.ref or ref
+        paths = [path] if path else args.path
+    else:
+        repo = args.repo
+        ref = args.ref
+        paths = args.path
+
+    try:
+        installed = install(repo, paths, ref, dest)
+    except RuntimeError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    if installed:
+        print(f"\nInstalled {len(installed)} skill(s) to {dest}/:")
+        for name in installed:
+            print(f"  - {name}")
+    else:
+        print("No skills were installed.", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())