# GitHub Issue Templates for Outreach

## Principles

- Lead with THEIR problem, not your solution
- Reference specific code/features they use
- Show concrete benefit with numbers
- Include migration snippet (1-3 lines)
- "You might find useful" tone, never "you should switch"
- Always disclose: "I'm the maintainer of X"

## Template 1: Performance Win (streaming/agent loops)

```markdown
Title: Potential performance improvement for {their_feature} with persistent WebSockets

Hi! I noticed {repo_name} uses async-openai for {what_they_do}.

I maintain [openai-oxide](https://github.com/fortunto2/openai-oxide), a Rust OpenAI client
that keeps a single WebSocket connection open across multiple API calls. In benchmarks with
sequential tool calls (similar to your {specific_pattern}), this reduces latency by ~40%
compared to HTTP REST — no TLS handshake overhead after the first request.

If you're interested, the migration is minimal:

```toml
# Cargo.toml
openai-oxide = { version = "0.9", features = ["websocket", "responses"] }
```

```rust
let mut session = client.ws_session().await?;
// reuse session across calls
let response = session.send(request).await?;
```

Happy to help if you'd like to try it. No pressure — just thought it might be relevant
given your use of {streaming/tool_calls/agent_loop}.

Disclosure: I'm the maintainer of openai-oxide.
```

## Template 2: Structured Outputs (type safety)

```markdown
Title: Auto-generated JSON schemas for structured outputs

Hi! Looking at {repo_name}, I see you're building JSON schemas manually for
{their_structured_usage}. You might find `openai-oxide`'s `parse::<T>()` useful —
it auto-generates the schema from your Rust types:

```rust
#[derive(Deserialize, JsonSchema)]
struct YourType { /* fields */ }

let result = client.chat().completions()
    .parse::<YourType>(request).await?;
// result.parsed is Option<YourType>
```

No manual schema construction, no drift between types and schemas.

Docs: https://fortunto2.github.io/openai-oxide/guides/structured-output.html

Disclosure: I maintain openai-oxide. Happy to answer questions.
```

## Template 3: WASM Deployment

```markdown
Title: WASM/Cloudflare Workers support for {repo_name}

Hi! I noticed {repo_name} {uses_wasm_or_edge_context}.

openai-oxide compiles to `wasm32-unknown-unknown` out of the box — streaming, structured
outputs, and retry logic all work in WASM. We have a live Cloudflare Workers demo:
https://cloudflare-worker-dioxus.nameless-sunset-8f24.workers.dev

```toml
openai-oxide = { version = "0.9", default-features = false, features = ["chat", "responses"] }
```

If edge deployment is on your roadmap, this might save you some cfg-gating work.

Disclosure: I maintain openai-oxide.
```

## Template 4: HTTP Optimizations (general)

```markdown
Title: HTTP/2 optimizations for OpenAI API calls

Hi! I saw {repo_name} makes OpenAI API calls via async-openai. You might see
a latency improvement with these HTTP-level optimizations that openai-oxide enables
by default:

- gzip compression (~30% smaller responses)
- TCP_NODELAY (lower latency)
- HTTP/2 keep-alive pings (prevents idle disconnects)
- HTTP/2 adaptive flow control
- Connection pooling (4 per host)

These are standard reqwest builder options — you could also add them to your current
setup. Here's the relevant code if helpful:
https://github.com/fortunto2/openai-oxide/blob/main/src/client.rs#L85

Disclosure: I maintain openai-oxide.
```

## Anti-patterns (never do this)

- "async-openai is slow/bad/outdated" — disrespectful
- "You should switch to X" — pushy
- Generic copy-paste to 50 repos — spam, gets you reported
- Issues on repos with <5 stars — waste of time
- Issues on archived repos — nobody home
- Multiple issues on same repo — harassment
- Not disclosing you're the maintainer — dishonest

#!/usr/bin/env python3
"""Enrich JSONL dependents with GitHub metadata via gh api.

Usage: python3 enrich.py <jsonl_path> [--batch 30]
"""

# list-env-sensitive-calls: allow gh — GH_HOST is how a user points this at their
# own GitHub host, so it is the interface here rather than noise, and a wrong host
# fails on authentication instead of returning plausible data.
import json
import subprocess
import sys
import time
from pathlib import Path


def gh_api(endpoint: str) -> dict | None:
    """Call gh api and return parsed JSON."""
    try:
        result = subprocess.run(
            ["gh", "api", endpoint, "--jq", "."],
            capture_output=True,
            text=True,
            timeout=15,
        )
        if result.returncode == 0:
            return json.loads(result.stdout)
    except Exception:
        pass
    return None


def enrich_jsonl(path: str, batch_size: int = 30):
    jsonl_path = Path(path)
    lines = jsonl_path.read_text().strip().split("\n")
    entries = [json.loads(line) for line in lines if line.strip()]

    enriched_count = 0
    skipped_count = 0

    for i, entry in enumerate(entries):
        if entry.get("phase") != "raw":
            continue

        repo = entry["repo"]
        print(f"[{i + 1}/{len(entries)}] {repo}...", end=" ", flush=True)

        data = gh_api(f"repos/{repo}")

        if data is None:
            entry["phase"] = "skipped"
            entry["verdict_reason"] = "404 or private"
            skipped_count += 1
            print("SKIP (404)")
        elif data.get("archived"):
            entry.update(
                {
                    "stars": data.get("stargazers_count", 0),
                    "description": data.get("description", ""),
                    "archived": True,
                    "phase": "skipped",
                    "verdict_reason": "archived",
                }
            )
            skipped_count += 1
            print(f"SKIP (archived, {data.get('stargazers_count', 0)}★)")
        elif data.get("fork") and data.get("stargazers_count", 0) < 5:
            entry.update(
                {
                    "stars": data.get("stargazers_count", 0),
                    "description": data.get("description", ""),
                    "archived": False,
                    "phase": "skipped",
                    "verdict_reason": "low-star fork",
                }
            )
            skipped_count += 1
            print(f"SKIP (fork, {data.get('stargazers_count', 0)}★)")
        else:
            entry.update(
                {
                    "stars": data.get("stargazers_count", 0),
                    "description": data.get("description", ""),
                    "language": data.get("language", ""),
                    "last_push": data.get("pushed_at", ""),
                    "archived": False,
                    "fork": data.get("fork", False),
                    "has_issues": data.get("has_issues", True),
                    "topics": data.get("topics", []),
                    "phase": "enriched",
                }
            )
            enriched_count += 1
            print(f"OK ({data.get('stargazers_count', 0)}★)")

        # Save after each batch
        if (enriched_count + skipped_count) % batch_size == 0:
            with open(jsonl_path, "w") as f:
                for e in entries:
                    f.write(json.dumps(e, ensure_ascii=False) + "\n")
            print(f"  [saved, {enriched_count} enriched, {skipped_count} skipped]")
            time.sleep(2)  # Rate limit pause between batches

    # Final save
    with open(jsonl_path, "w") as f:
        for e in entries:
            f.write(json.dumps(e, ensure_ascii=False) + "\n")

    print(f"\nDone: {enriched_count} enriched, {skipped_count} skipped")


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: enrich.py <jsonl_path> [--batch N]")
        sys.exit(1)

    batch = 30
    if "--batch" in sys.argv:
        idx = sys.argv.index("--batch")
        batch = int(sys.argv[idx + 1])

    enrich_jsonl(sys.argv[1], batch_size=batch)

#!/usr/bin/env python3
"""Evaluate a single repo from JSONL — read README + Cargo.toml via gh api.

Usage: python3 evaluate.py <jsonl_path> <owner/repo>
       python3 evaluate.py <jsonl_path> --next       # Pick next enriched by stars
"""

# list-env-sensitive-calls: allow gh — GH_HOST is how a user points this at their
# own GitHub host, so it is the interface here rather than noise, and a wrong host
# fails on authentication instead of returning plausible data.
import base64
import json
import subprocess
import sys
from datetime import datetime
from pathlib import Path


def gh_api(endpoint: str, jq: str = ".") -> str | None:
    try:
        result = subprocess.run(
            ["gh", "api", endpoint, "--jq", jq],
            capture_output=True,
            text=True,
            timeout=15,
        )
        if result.returncode == 0:
            return result.stdout.strip()
    except Exception:
        pass
    return None


def gh_content(repo: str, path: str) -> str | None:
    """Fetch file content from repo via gh api."""
    raw = gh_api(f"repos/{repo}/contents/{path}", ".content")
    if raw:
        try:
            return base64.b64decode(raw).decode("utf-8", errors="replace")
        except Exception:
            pass
    return None


def evaluate_repo(entry: dict) -> dict:
    """Evaluate a single repo and return updated entry."""
    repo = entry["repo"]
    stars = entry.get("stars", 0)

    print(f"\nEvaluating: {repo} ({stars}★)")
    print("=" * 50)

    # Read README
    readme = gh_content(repo, "README.md")
    if readme:
        print(f"README: {len(readme)} chars")
        print(f"  Preview: {readme[:200]}...")
    else:
        print("README: not found")

    # Read Cargo.toml
    cargo = gh_content(repo, "Cargo.toml")
    if cargo:
        print("Cargo.toml: found")
        # Extract async-openai usage
        for line in cargo.split("\n"):
            if "async-openai" in line.lower() or "openai" in line.lower():
                print(f"  {line.strip()}")
    else:
        print("Cargo.toml: not found (maybe workspace?)")
        # Try common paths
        for alt in ["crates/core/Cargo.toml", "src/Cargo.toml", "backend/Cargo.toml"]:
            cargo = gh_content(repo, alt)
            if cargo:
                print(f"  Found at {alt}")
                break

    # Detect features
    features = []
    all_text = (readme or "") + (cargo or "")
    lower_text = all_text.lower()

    feature_signals = {
        "streaming": ["stream", "sse", "event-stream", "create_stream"],
        "tools": ["tool_call", "function_call", "tool_choice", "function_calling"],
        "structured": ["json_schema", "response_format", "structured", "schemars"],
        "embeddings": ["embedding", "vector", "similarity"],
        "agent_loop": ["agent", "loop", "iteration", "multi-turn", "conversation"],
        "audio": ["audio", "transcription", "speech", "whisper", "tts"],
        "images": ["image", "dall-e", "generate.*image"],
        "realtime": ["realtime", "websocket", "wss://"],
        "wasm": ["wasm", "cloudflare", "worker", "edge"],
    }

    for feature, signals in feature_signals.items():
        if any(s in lower_text for s in signals):
            features.append(feature)

    print(f"Features detected: {features}")

    # Determine our advantages for this repo
    advantage_map = {
        "streaming": "stream_helpers",
        "tools": "structured_outputs",
        "structured": "structured_outputs",
        "agent_loop": "persistent_websockets",
        "realtime": "persistent_websockets",
        "wasm": "wasm_builtin",
    }
    our_advantages = list(set(advantage_map[f] for f in features if f in advantage_map))
    print(f"Our advantages: {our_advantages}")

    # Score
    score = 0
    # Stars component (0-30)
    if stars >= 1000:
        score += 30
    elif stars >= 100:
        score += 25
    elif stars >= 20:
        score += 15
    elif stars >= 5:
        score += 10

    # Activity (0-20)
    last_push = entry.get("last_push", "")
    if last_push:
        try:
            pushed = datetime.fromisoformat(last_push.replace("Z", "+00:00"))
            days = (datetime.now(pushed.tzinfo) - pushed).days
            if days < 30:
                score += 20
            elif days < 90:
                score += 15
            elif days < 180:
                score += 10
        except Exception:
            score += 5

    # Feature fit (0-30)
    score += min(len(our_advantages) * 10, 30)

    # Approachability (0-20)
    if entry.get("has_issues", True):
        score += 10
    if not entry.get("fork", False):
        score += 10

    # Verdict
    if score >= 60:
        verdict = "target"
    elif score >= 30:
        verdict = "maybe"
    else:
        verdict = "skip"

    print(f"Score: {score}/100 → {verdict}")

    entry.update(
        {
            "phase": "evaluated",
            "score": score,
            "features_used": features,
            "our_advantages": our_advantages,
            "verdict": verdict,
            "evaluated_at": datetime.now().isoformat(),
        }
    )

    return entry


def main():
    if len(sys.argv) < 2:
        print("Usage: evaluate.py <jsonl_path> <owner/repo>")
        print("       evaluate.py <jsonl_path> --next")
        sys.exit(1)

    jsonl_path = Path(sys.argv[1])
    lines = jsonl_path.read_text().strip().split("\n")
    entries = [json.loads(line) for line in lines if line.strip()]

    if len(sys.argv) >= 3 and sys.argv[2] == "--next":
        # Pick next enriched by stars
        enriched = [e for e in entries if e.get("phase") == "enriched"]
        enriched.sort(key=lambda x: x.get("stars", 0), reverse=True)
        if not enriched:
            print("No enriched repos to evaluate")
            sys.exit(0)
        target_repo = enriched[0]["repo"]
    else:
        target_repo = sys.argv[2]

    # Find and evaluate
    for i, entry in enumerate(entries):
        if entry["repo"] == target_repo:
            entries[i] = evaluate_repo(entry)
            break
    else:
        print(f"Repo not found: {target_repo}")
        sys.exit(1)

    # Save
    with open(jsonl_path, "w") as f:
        for e in entries:
            f.write(json.dumps(e, ensure_ascii=False) + "\n")

    print(f"\nSaved to {jsonl_path}")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Convert raw repo list (one per line) to JSONL.

Usage: python3 init_jsonl.py <repos_file> <output_jsonl>
       cat repos.txt | python3 init_jsonl.py - output.jsonl
"""

import json
import sys
from pathlib import Path


def main():
    if len(sys.argv) < 3:
        print("Usage: init_jsonl.py <repos_file_or_-> <output.jsonl>")
        sys.exit(1)

    src = sys.argv[1]
    out = Path(sys.argv[2])

    if src == "-":
        lines = sys.stdin.read().strip().split("\n")
    else:
        lines = Path(src).read_text().strip().split("\n")

    repos = [line.strip() for line in lines if line.strip() and "/" in line]

    with open(out, "w") as f:
        for repo in repos:
            entry = {
                "repo": repo,
                "url": f"https://github.com/{repo}",
                "phase": "raw",
                "stars": 0,
                "description": "",
                "language": "",
                "last_push": "",
                "archived": False,
                "score": 0,
                "features_used": [],
                "our_advantages": [],
                "verdict": "",
                "verdict_reason": "",
                "draft_title": "",
                "draft_body": "",
                "issue_url": "",
                "evaluated_at": "",
                "notes": "",
            }
            f.write(json.dumps(entry, ensure_ascii=False) + "\n")

    print(f"Created {out} with {len(repos)} entries")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Show outreach pipeline status from JSONL.

Usage: python3 status.py <jsonl_path> [--targets] [--csv]
"""

import json
import sys
from collections import Counter
from pathlib import Path


def show_status(path: str, show_targets: bool = False, csv_mode: bool = False):
    jsonl_path = Path(path)
    if not jsonl_path.exists():
        print(f"Not found: {path}")
        sys.exit(1)

    lines = jsonl_path.read_text().strip().split("\n")
    entries = [json.loads(line) for line in lines if line.strip()]

    # Phase counts
    phases = Counter(e.get("phase", "raw") for e in entries)
    verdicts = Counter(
        e.get("verdict", "") for e in entries if e.get("phase") == "evaluated"
    )

    if csv_mode:
        # CSV output for spreadsheet
        print("repo,stars,phase,verdict,features_used,our_advantages,verdict_reason")
        for e in sorted(entries, key=lambda x: x.get("stars", 0), reverse=True):
            features = ";".join(e.get("features_used", []))
            advantages = ";".join(e.get("our_advantages", []))
            print(
                f"{e['repo']},{e.get('stars', 0)},{e.get('phase', 'raw')},"
                f"{e.get('verdict', '')},{features},{advantages},"
                f"{e.get('verdict_reason', '')}"
            )
        return

    # Summary
    print("\nOutreach Pipeline Status")
    print(f"{'=' * 35}")
    print(f"Total repos:     {len(entries)}")
    print()

    print("Phase            Count")
    print(f"{'-' * 35}")
    for phase in ["raw", "enriched", "evaluated", "drafted", "posted", "skipped"]:
        count = phases.get(phase, 0)
        if count > 0:
            print(f"  {phase:<15} {count:>5}")
            if phase == "evaluated":
                for v in ["target", "maybe", "skip"]:
                    vc = verdicts.get(v, 0)
                    if vc > 0:
                        print(f"    -> {v:<13} {vc:>3}")
    print(f"{'-' * 35}")

    # Top targets
    targets = [
        e
        for e in entries
        if e.get("verdict") == "target" and e.get("phase") in ("evaluated", "drafted")
    ]
    targets.sort(key=lambda x: x.get("stars", 0), reverse=True)

    if targets:
        print(f"\nTop targets ({len(targets)}):")
        for t in targets[:10]:
            advantages = ", ".join(t.get("our_advantages", [])[:3])
            print(f"  {t.get('stars', 0):>6}★  {t['repo']:<40} {advantages}")

    # Top enriched (not yet evaluated)
    if show_targets:
        pending = [e for e in entries if e.get("phase") == "enriched"]
        pending.sort(key=lambda x: x.get("stars", 0), reverse=True)
        if pending:
            print(f"\nNext to evaluate ({len(pending)} pending):")
            for p in pending[:15]:
                desc = (p.get("description") or "")[:50]
                print(f"  {p.get('stars', 0):>6}★  {p['repo']:<40} {desc}")


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: status.py <jsonl_path> [--targets] [--csv]")
        sys.exit(1)

    show_status(
        sys.argv[1],
        show_targets="--targets" in sys.argv,
        csv_mode="--csv" in sys.argv,
    )