grad-agent 0.1.1__py3-none-any.whl

grad_agent/catalog_sync.py

@@ -0,0 +1,174 @@
+"""Extend the project catalog from GitHub + HuggingFace + local NINTE dirs.
+
+Writes/updates `catalog.json` in the grad-agent directory. Each entry has the
+same shape as the seed `PROJECTS` list in projects.py:
+    {name, pitch, link, tags}
+Claude Haiku distils each source (repo, model, local README) into the pitch
+and tags. Existing entries are updated in place; new ones appended.
+"""
+from __future__ import annotations
+import os, json, re, time
+from pathlib import Path
+
+from . import config as _cfg
+_cfg.load_env_file()
+
+from .sources import github as gh
+from .sources import hf
+
+try:
+    import anthropic
+except Exception:
+    anthropic = None
+
+
+def _catalog_path() -> Path:
+    return _cfg.data_dir() / "catalog.json"
+
+
+def _projects_dir() -> Path:
+    prof = _cfg.load_profile()
+    if prof.projects_dir:
+        return Path(prof.projects_dir).expanduser()
+    return Path(os.environ.get("NINTE_ROOT", str(Path.home())))
+
+# Skip these local dirs when scanning _projects_dir()
+SKIP_LOCAL = {"GRAD", "portfolio", "SNAPSHOT", "Kwabena.zip"}
+
+SYSTEM = (
+    "You extract a compact JSON record from a project description. Return a "
+    "strict JSON object with keys: pitch (one sentence, 25 to 45 words, in "
+    "Kwabena's voice, direct and grounded in the actual work described, no "
+    "cliches, no dashes), tags (a list of 5 to 12 short lowercase phrases "
+    "describing the technical area, methods, and domain, e.g. 'nlp', 'llm', "
+    "'african languages', 'yolo', 'time series'). Nothing else. No prose "
+    "outside the JSON."
+)
+
+
+def _distil(name: str, kind: str, description: str, extra: str = "",
+            model: str = "claude-haiku-4-5-20251001") -> dict:
+    if anthropic is None or not os.environ.get("ANTHROPIC_API_KEY"):
+        # Heuristic: pitch = first 40 words of description, tags = topics/tags
+        pitch = " ".join((description or f"{kind} named {name}").split()[:40])
+        return {"pitch": pitch, "tags": []}
+    client = anthropic.Anthropic()
+    user = (
+        f"KIND: {kind}\nNAME: {name}\nDESCRIPTION: {description}\n\n"
+        f"EXTRA CONTEXT (README or metadata):\n{extra[:3000]}\n\n"
+        f"Return the JSON now."
+    )
+    m = client.messages.create(
+        model=model, max_tokens=400, system=SYSTEM,
+        messages=[{"role": "user", "content": user}],
+    )
+    raw = m.content[0].text.strip()
+    # tolerate ```json fences
+    raw = re.sub(r"^```(?:json)?", "", raw).rstrip("`").strip()
+    try:
+        obj = json.loads(raw)
+        obj["pitch"] = obj.get("pitch", "").replace("—", ", ").replace("–", ", ")
+        return {"pitch": obj.get("pitch", ""), "tags": obj.get("tags", []) or []}
+    except Exception:
+        return {"pitch": (description or "")[:200], "tags": []}
+
+
+def _load() -> dict:
+    if _catalog_path().exists():
+        return json.loads(_catalog_path().read_text())
+    return {"projects": {}, "last_synced": None}
+
+
+def _save(cat: dict) -> None:
+    cat["last_synced"] = time.strftime("%Y-%m-%d %H:%M")
+    _catalog_path().write_text(json.dumps(cat, indent=2))
+
+
+def _upsert(cat: dict, key: str, entry: dict) -> None:
+    cat["projects"][key] = entry
+
+
+def sync_github() -> int:
+    cat = _load(); added = 0
+    for r in gh.list_repos():
+        if r["fork"] or r["archived"]: continue
+        readme = gh.fetch_readme(r["full_name"])
+        d = _distil(
+            name=r["name"],
+            kind="github repo",
+            description=r["description"] or "",
+            extra=(readme or "") + "\nTopics: " + ", ".join(r["topics"]),
+        )
+        entry = {
+            "name": r["name"],
+            "pitch": d["pitch"] or (r["description"] or r["name"]),
+            "link": r["html_url"],
+            "tags": list(dict.fromkeys(d["tags"] + r["topics"])),
+            "source": "github",
+            "language": r["language"],
+            "stars": r["stars"],
+        }
+        _upsert(cat, f"gh:{r['full_name']}", entry); added += 1
+    _save(cat); return added
+
+
+def sync_hf() -> int:
+    cat = _load(); added = 0
+    for m in hf.list_models() + hf.list_datasets():
+        readme = hf.fetch_readme(m["id"], kind=m["kind"] + "s")
+        d = _distil(
+            name=m["id"],
+            kind=f"huggingface {m['kind']}",
+            description=(m.get("pipeline_tag") or "") + " " + ", ".join(m["tags"][:10]),
+            extra=readme,
+        )
+        entry = {
+            "name": m["id"],
+            "pitch": d["pitch"] or f"{m['kind']} at {m['id']}",
+            "link": m["url"],
+            "tags": list(dict.fromkeys(d["tags"] + m["tags"])),
+            "source": "huggingface",
+            "downloads": m["downloads"],
+            "likes": m["likes"],
+        }
+        _upsert(cat, f"hf:{m['kind']}:{m['id']}", entry); added += 1
+    _save(cat); return added
+
+
+def sync_local() -> int:
+    cat = _load(); added = 0
+    for child in _projects_dir().iterdir():
+        if not child.is_dir() or child.name in SKIP_LOCAL: continue
+        readme_text = ""
+        for cand in ("README.md", "Readme.md", "readme.md", "README.txt"):
+            p = child / cand
+            if p.exists():
+                readme_text = p.read_text(errors="ignore")[:4000]; break
+        if not readme_text and not any((child / c).exists() for c in ("package.json", "requirements.txt")):
+            continue
+        d = _distil(
+            name=child.name, kind="local project directory",
+            description="", extra=readme_text,
+        )
+        entry = {
+            "name": child.name,
+            "pitch": d["pitch"] or child.name,
+            "link": str(child),
+            "tags": d["tags"],
+            "source": "local",
+        }
+        _upsert(cat, f"local:{child.name}", entry); added += 1
+    _save(cat); return added
+
+
+def sync_all() -> dict:
+    return {
+        "github": sync_github(),
+        "huggingface": sync_hf(),
+        "local": sync_local(),
+        "catalog_path": str(_catalog_path()),
+    }
+
+
+if __name__ == "__main__":
+    print(sync_all())

grad_agent/cli.py

@@ -0,0 +1,184 @@
+"""grad-agent CLI.
+
+Subcommands:
+  init          Interactive setup: writes ~/.grad-agent/profile.yaml + .env
+  server        Start the MCP stdio server (for `claude mcp add`).
+  run           Run today's outreach batch and email the review inbox.
+  sync          Sync catalog from GitHub + HuggingFace + local projects_dir.
+  register-claude  Print the `claude mcp add` command tailored to this install.
+  path          Print resolved GRAD_AGENT_HOME.
+"""
+from __future__ import annotations
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+from . import config
+
+
+def _prompt(label: str, default: str = "") -> str:
+    suffix = f" [{default}]" if default else ""
+    v = input(f"{label}{suffix}: ").strip()
+    return v or default
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    home = config.ensure_home()
+    print(f"Setting up grad-agent at {home}\n")
+
+    tmpl_dir = config.TEMPLATES
+    profile_dst = config.profile_path()
+    env_dst = config.env_path()
+    programs_dst = config.programs_path()
+
+    if profile_dst.exists() and not args.force:
+        print(f"profile.yaml already exists at {profile_dst}. Use --force to overwrite.")
+    else:
+        shutil.copy(tmpl_dir / "profile.example.yaml", profile_dst)
+        print(f"wrote {profile_dst}")
+
+    if not programs_dst.exists() or args.force:
+        shutil.copy(tmpl_dir / "programs.example.yaml", programs_dst)
+        print(f"wrote {programs_dst}")
+
+    if env_dst.exists() and not args.force:
+        print(f".env already exists at {env_dst}. Use --force to overwrite.")
+    else:
+        shutil.copy(tmpl_dir / "env.example", env_dst)
+        print(f"wrote {env_dst}")
+
+    if args.interactive:
+        print("\nQuick setup, press Enter to keep defaults or fill later:\n")
+        import yaml
+        prof = yaml.safe_load(profile_dst.read_text()) or {}
+        prof["name"] = _prompt("Full name", prof.get("name", ""))
+        prof["identity_line"] = _prompt(
+            'One-line identity (e.g. "a Computer Science graduate from KNUST")',
+            prof.get("identity_line", ""),
+        )
+        prof["portfolio"] = _prompt("Portfolio URL", prof.get("portfolio", ""))
+        prof["cv_path"] = _prompt("Absolute path to CV pdf", prof.get("cv_path", ""))
+        prof["transcript_path"] = _prompt("Absolute path to transcript pdf", prof.get("transcript_path", ""))
+        prof["degree_status"] = _prompt("Highest degree (bachelors/masters)", prof.get("degree_status", "bachelors"))
+        prof["target_term"] = _prompt("Target term", prof.get("target_term", "Fall 2027"))
+        prof["target_degree"] = _prompt("Target degree (PhD/MSc)", prof.get("target_degree", "PhD"))
+        prof["review_email"] = _prompt("Review inbox (where drafts land)", prof.get("review_email", ""))
+        profile_dst.write_text(yaml.safe_dump(prof, sort_keys=False))
+        print(f"\nupdated {profile_dst}")
+
+    print("\nNext steps:")
+    print(f"  1. Fill in secrets in {env_dst} (ANTHROPIC_API_KEY, SMTP_*)")
+    print(f"  2. Edit {profile_dst} to add your seed_projects (3 to 10 flagships)")
+    print(f"  3. Optional: edit {programs_dst} to add target programs")
+    print(f"  4. Run: grad-agent sync           # scan projects")
+    print(f"  5. Run: grad-agent run --dry-run  # preview one batch")
+    print(f"  6. Run: grad-agent register-claude  # get MCP install command")
+    return 0
+
+
+def cmd_server(_: argparse.Namespace) -> int:
+    from . import server as _server
+    _server.mcp.run()
+    return 0
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    from . import daily_run
+    res = daily_run.run_batch(n=args.n, area=args.area or None, dry_run=args.dry_run)
+    print(res)
+    return 0
+
+
+def cmd_sync(args: argparse.Namespace) -> int:
+    from . import catalog_sync
+    src = args.source or "all"
+    print(getattr(catalog_sync, f"sync_{src}", catalog_sync.sync_all)() if src != "all"
+          else catalog_sync.sync_all())
+    return 0
+
+
+def _resolve_grad_agent_exe() -> str:
+    """Return the command Claude Code should run to launch this install.
+    Order of preference:
+      1. `grad-agent` on PATH  (clean form, works after `pipx ensurepath`)
+      2. sys.argv[0] if it looks like a grad-agent script  (matches how the
+         user just invoked us)
+      3. A `grad-agent` binary next to the current Python  (pipx layout)
+      4. `<sys.executable> -m grad_agent.cli`  (universal fallback)
+    """
+    from pathlib import Path
+
+    on_path = shutil.which("grad-agent")
+    if on_path:
+        return on_path
+
+    argv0 = Path(sys.argv[0]) if sys.argv and sys.argv[0] else None
+    if argv0 and argv0.is_absolute() and argv0.name.startswith("grad-agent"):
+        return str(argv0)
+
+    adj = Path(sys.executable).parent / "grad-agent"
+    if adj.exists():
+        return str(adj)
+
+    return f"{sys.executable} -m grad_agent.cli"
+
+
+def cmd_register_claude(_: argparse.Namespace) -> int:
+    exe = _resolve_grad_agent_exe()
+    on_path = shutil.which("grad-agent")
+    cmd = f"claude mcp add grad-agent {exe} server"
+    print("Run this once to register with Claude Code:\n")
+    print(f"    {cmd}\n")
+    if not on_path:
+        print("Note: `grad-agent` is not on your PATH yet.")
+        print("Run `pipx ensurepath` and open a new terminal to get the shorter form")
+        print("`claude mcp add grad-agent grad-agent server`.\n")
+    print("Then in a Claude Code session type /mcp to confirm it's connected.")
+    return 0
+
+
+def cmd_path(_: argparse.Namespace) -> int:
+    print(config.home())
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="grad-agent", description=__doc__)
+    sub = parser.add_subparsers(dest="cmd")
+
+    p_init = sub.add_parser("init", help="Interactive setup")
+    p_init.add_argument("--force", action="store_true")
+    p_init.add_argument("--interactive", action="store_true", default=True)
+    p_init.add_argument("--no-interactive", dest="interactive", action="store_false")
+    p_init.set_defaults(func=cmd_init)
+
+    p_server = sub.add_parser("server", help="Start MCP stdio server")
+    p_server.set_defaults(func=cmd_server)
+
+    p_run = sub.add_parser("run", help="Run today's outreach batch")
+    p_run.add_argument("-n", type=int, default=3)
+    p_run.add_argument("--area", default="")
+    p_run.add_argument("--dry-run", action="store_true")
+    p_run.set_defaults(func=cmd_run)
+
+    p_sync = sub.add_parser("sync", help="Sync project catalog")
+    p_sync.add_argument("--source", choices=["all", "github", "hf", "local"], default="all")
+    p_sync.set_defaults(func=cmd_sync)
+
+    p_reg = sub.add_parser("register-claude", help="Print the claude mcp add command")
+    p_reg.set_defaults(func=cmd_register_claude)
+
+    p_path = sub.add_parser("path", help="Print GRAD_AGENT_HOME")
+    p_path.set_defaults(func=cmd_path)
+
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help(); return 1
+
+    config.load_env_file()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

grad_agent/config.py

@@ -0,0 +1,114 @@
+"""Centralised config + paths + profile loader for grad-agent.
+
+User data location (in priority order):
+  1. $GRAD_AGENT_HOME
+  2. ~/.grad-agent/
+  3. Current working directory (for legacy/dev)
+
+Layout under HOME:
+  profile.yaml     user identity + preferences
+  programs.yaml    user's target programs (seeded from template on init)
+  .env             secrets only (SMTP, ANTHROPIC_API_KEY, GITHUB_TOKEN, ...)
+  data/            outreach_log.xlsx, lor_log.xlsx, catalog.json, db.sqlite
+  drafts/          per-school drafts
+"""
+from __future__ import annotations
+import os
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+
+try:
+    import yaml
+except Exception:
+    yaml = None
+
+
+PACKAGE_ROOT = Path(__file__).parent
+TEMPLATES = PACKAGE_ROOT / "templates"
+
+
+def home() -> Path:
+    env = os.environ.get("GRAD_AGENT_HOME")
+    if env:
+        return Path(env).expanduser().resolve()
+    default = Path.home() / ".grad-agent"
+    if default.exists():
+        return default
+    # Legacy fallback: the folder containing the package
+    return PACKAGE_ROOT.parent
+
+
+def ensure_home() -> Path:
+    h = home()
+    h.mkdir(parents=True, exist_ok=True)
+    (h / "data").mkdir(exist_ok=True)
+    (h / "drafts").mkdir(exist_ok=True)
+    return h
+
+
+def profile_path() -> Path:  return home() / "profile.yaml"
+def programs_path() -> Path: return home() / "programs.yaml"
+def env_path() -> Path:      return home() / ".env"
+
+def data_dir() -> Path:      ensure_home(); return home() / "data"
+def drafts_dir() -> Path:    ensure_home(); return home() / "drafts"
+
+
+@dataclass
+class Profile:
+    name: str = ""
+    identity_line: str = ""
+    portfolio: str = ""
+    cv_path: str = ""
+    transcript_path: str = ""
+    degree_status: str = "bachelors"     # bachelors | masters
+    target_term: str = "Fall 2027"
+    target_degree: str = "PhD"           # PhD | MSc
+    research_areas: list[str] = field(default_factory=list)
+    projects_dir: str = ""
+    seed_projects: list[dict] = field(default_factory=list)
+    blog: dict = field(default_factory=dict)     # optional plugin config
+    review_email: str = ""                       # where drafts are sent
+
+    @property
+    def has_masters(self) -> bool:
+        return (self.degree_status or "").lower() == "masters"
+
+
+@lru_cache(maxsize=1)
+def load_profile() -> Profile:
+    p = profile_path()
+    if not p.exists() or yaml is None:
+        return Profile()
+    data = yaml.safe_load(p.read_text()) or {}
+    return Profile(
+        name=data.get("name", ""),
+        identity_line=data.get("identity_line", ""),
+        portfolio=data.get("portfolio", ""),
+        cv_path=str(Path(data.get("cv_path", "")).expanduser()) if data.get("cv_path") else "",
+        transcript_path=str(Path(data.get("transcript_path", "")).expanduser()) if data.get("transcript_path") else "",
+        degree_status=data.get("degree_status", "bachelors"),
+        target_term=data.get("target_term", "Fall 2027"),
+        target_degree=data.get("target_degree", "PhD"),
+        research_areas=data.get("research_areas", []) or [],
+        projects_dir=str(Path(data.get("projects_dir", "")).expanduser()) if data.get("projects_dir") else "",
+        seed_projects=data.get("seed_projects", []) or [],
+        blog=data.get("blog", {}) or {},
+        review_email=data.get("review_email", ""),
+    )
+
+
+def load_env_file() -> None:
+    """Load .env from GRAD_AGENT_HOME. Silent if missing."""
+    try:
+        from dotenv import load_dotenv
+    except Exception:
+        return
+    p = env_path()
+    if p.exists():
+        load_dotenv(p, override=False)
+    # legacy: also try package-local .env
+    legacy = PACKAGE_ROOT.parent / ".env"
+    if legacy.exists():
+        load_dotenv(legacy, override=False)