grad-agent 0.1.1__tar.gz

grad_agent-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+.env
+db.sqlite
+drafts/
+__pycache__/
+*.pyc
+.venv/
+*.log
+*.xlsx

grad_agent-0.1.1/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: grad-agent
+Version: 0.1.1
+Summary: Autonomous MCP agent for graduate school applications: prof discovery + verified cold emails + SOP drafting + application tracking.
+Project-URL: Homepage, https://github.com/i-ninte/grad-agent
+Project-URL: Issues, https://github.com/i-ninte/grad-agent/issues
+Author-email: Kwabena Obeng <slyobeng111@gmail.com>
+License: MIT
+Keywords: agent,anthropic,claude,cold-email,grad-school,mcp,phd,sop
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: fastmcp>=0.2.0
+Requires-Dist: feedparser>=6.0.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: markdown>=3.6
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pandas>=2.0
+Requires-Dist: pymdown-extensions>=10.7
+Requires-Dist: pypdf>=4.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: blog
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# grad-agent
+
+An autonomous MCP agent that helps you apply to fully funded MS and PhD programs.
+
+- Discovers professors on arXiv in your research areas
+- Verifies each candidate is actually faculty (Semantic Scholar, h-index, papers)
+- Scrapes their lab page for a recruiting signal + email address
+- Matches them to your strongest shipped project
+- Drafts a specific, fact-checked cold email (Claude Haiku authors + verifies claims against paper abstracts)
+- Compiles a per-school SOP to PDF (LaTeX)
+- Tracks everything in xlsx: outreach, LOR requests, program deadlines
+- Emails every draft to your inbox for review; nothing is sent to a professor without you
+
+Runs as a stdio MCP server for Claude Code / Claude Desktop, or as a plain CLI.
+
+## Install
+
+```bash
+pipx install grad-agent
+# or, if you prefer pip in a venv
+python3 -m venv .venv && source .venv/bin/activate
+pip install grad-agent
+```
+
+## Set up in 5 minutes
+
+```bash
+grad-agent init
+```
+
+This writes:
+
+- `~/.grad-agent/profile.yaml` — your identity, projects, preferences
+- `~/.grad-agent/programs.yaml` — target programs (seeded)
+- `~/.grad-agent/.env` — secrets template
+
+Fill in `~/.grad-agent/.env`:
+
+```
+ANTHROPIC_API_KEY=sk-ant-...
+SMTP_SERVER=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USERNAME=you@gmail.com
+SMTP_PASSWORD=<gmail app password>
+SMTP_FROM=you@gmail.com
+# Optional:
+GITHUB_USERNAME=your-gh
+GITHUB_TOKEN=github_pat_...
+HF_USERNAME=your-hf
+```
+
+Fill in the important bits of `~/.grad-agent/profile.yaml`:
+
+- `name`, `identity_line`, `portfolio`
+- `cv_path`, `transcript_path` (absolute paths)
+- `degree_status: bachelors | masters` (drives PhD eligibility gating)
+- `target_term`, `target_degree`
+- `research_areas: [nlp, ai4health, ...]`
+- `seed_projects:` 3 to 10 flagship projects with `name`, `pitch`, `link`, `tags`
+
+Then:
+
+```bash
+grad-agent sync        # scan projects (GitHub + HF + local)
+grad-agent run         # one batch, drafts land in your inbox
+```
+
+## Register with Claude Code
+
+```bash
+grad-agent register-claude
+```
+
+Prints the exact `claude mcp add` command. Once registered, `/mcp` in Claude Code shows `grad-agent` with ~25 tools.
+
+## Register with Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "grad-agent": {
+      "command": "grad-agent",
+      "args": ["server"]
+    }
+  }
+}
+```
+
+## Daily autonomous run (macOS)
+
+The package ships a launchd plist template. To fire every day at 08:00:
+
+```bash
+cp /path/to/grad_agent/templates/com.gradagent.daily.plist ~/Library/LaunchAgents/
+launchctl load ~/Library/LaunchAgents/com.gradagent.daily.plist
+```
+
+Every morning: 3 verified faculty leads, hooks fact-checked against paper abstracts, in your inbox for review.
+
+## What each MCP tool does
+
+| Tool | Purpose |
+|---|---|
+| `run_daily_batch(n, area)` | Full pipeline: verify → recruiting → hook + verify → draft → log |
+| `outreach_log_view(limit)` | Show last N rows of the outreach xlsx |
+| `outreach_mark_sent(prof, uni)` | Flag a row as actually sent to the prof |
+| `sync_catalog(source)` | Pull projects from `github`, `hf`, or `local` |
+| `list_projects_in_catalog()` | Show every project the matcher can see |
+| `list_programs()` | Your target programs |
+| `upcoming_deadlines(days)` | Any program deadline in the next N days |
+| `lor_add / lor_outstanding / lor_mark` | Recommendation-letter tracker |
+| `draft_cold_email(...)` | Manual per-prof draft |
+| `draft_sop(...)` | Compile a Columbia-style SOP PDF for one school |
+| `send_draft_to_me(path)` | Ship any draft file to your review inbox |
+| `discover_profs(area)` | arXiv + OpenReview scan (raw candidates, no verification) |
+
+Blog publishing tools (`publish_article`, `update_article`, ...) are gated behind `blog.enabled: true` in `profile.yaml` and are specific to the author's Turso-backed Next.js portfolio. Most users can ignore them.
+
+## What the agent will not do
+
+- Send any email to a professor. Every send is manual, from your Gmail, after you read the draft.
+- Fabricate a paper claim. The hook goes through a second Claude call that rejects any claim not present in the abstracts, and rewrites.
+- Draft for programs you are ineligible for. If your `degree_status` is `bachelors`, PhD programs that require an MSc first are filtered out.
+
+## Requirements
+
+- Python 3.10+
+- macOS or Linux (Windows untested)
+- `pdflatex` on PATH if you want SOP PDFs (macOS: MacTeX; Ubuntu: `texlive-latex-recommended`)
+- Anthropic API key
+- Gmail (or another SMTP) for the review-mailer
+
+## Where your data lives
+
+Everything is under `~/.grad-agent/` by default, or `$GRAD_AGENT_HOME` if set:
+
+```
+~/.grad-agent/
+  profile.yaml         identity + preferences
+  programs.yaml        target programs
+  .env                 secrets (gitignored)
+  data/
+    outreach_log.xlsx  every prof surfaced or drafted
+    lor_log.xlsx       recommendation-letter tracker
+    catalog.json       synced projects (GitHub + HF + local)
+    db.sqlite          drafts + status
+  drafts/              per-school SOP + email drafts
+```
+
+## Contributing
+
+MIT licensed. PRs welcome for: more program templates, non-Gmail SMTP presets, non-arXiv source adapters, and better prof-verification heuristics.
+
+## Author
+
+Kwabena Obeng · [i-ninte.github.io/portfolio/](https://i-ninte.github.io/portfolio/)

grad_agent-0.1.1/README.md

@@ -0,0 +1,158 @@
+# grad-agent
+
+An autonomous MCP agent that helps you apply to fully funded MS and PhD programs.
+
+- Discovers professors on arXiv in your research areas
+- Verifies each candidate is actually faculty (Semantic Scholar, h-index, papers)
+- Scrapes their lab page for a recruiting signal + email address
+- Matches them to your strongest shipped project
+- Drafts a specific, fact-checked cold email (Claude Haiku authors + verifies claims against paper abstracts)
+- Compiles a per-school SOP to PDF (LaTeX)
+- Tracks everything in xlsx: outreach, LOR requests, program deadlines
+- Emails every draft to your inbox for review; nothing is sent to a professor without you
+
+Runs as a stdio MCP server for Claude Code / Claude Desktop, or as a plain CLI.
+
+## Install
+
+```bash
+pipx install grad-agent
+# or, if you prefer pip in a venv
+python3 -m venv .venv && source .venv/bin/activate
+pip install grad-agent
+```
+
+## Set up in 5 minutes
+
+```bash
+grad-agent init
+```
+
+This writes:
+
+- `~/.grad-agent/profile.yaml` — your identity, projects, preferences
+- `~/.grad-agent/programs.yaml` — target programs (seeded)
+- `~/.grad-agent/.env` — secrets template
+
+Fill in `~/.grad-agent/.env`:
+
+```
+ANTHROPIC_API_KEY=sk-ant-...
+SMTP_SERVER=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USERNAME=you@gmail.com
+SMTP_PASSWORD=<gmail app password>
+SMTP_FROM=you@gmail.com
+# Optional:
+GITHUB_USERNAME=your-gh
+GITHUB_TOKEN=github_pat_...
+HF_USERNAME=your-hf
+```
+
+Fill in the important bits of `~/.grad-agent/profile.yaml`:
+
+- `name`, `identity_line`, `portfolio`
+- `cv_path`, `transcript_path` (absolute paths)
+- `degree_status: bachelors | masters` (drives PhD eligibility gating)
+- `target_term`, `target_degree`
+- `research_areas: [nlp, ai4health, ...]`
+- `seed_projects:` 3 to 10 flagship projects with `name`, `pitch`, `link`, `tags`
+
+Then:
+
+```bash
+grad-agent sync        # scan projects (GitHub + HF + local)
+grad-agent run         # one batch, drafts land in your inbox
+```
+
+## Register with Claude Code
+
+```bash
+grad-agent register-claude
+```
+
+Prints the exact `claude mcp add` command. Once registered, `/mcp` in Claude Code shows `grad-agent` with ~25 tools.
+
+## Register with Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "grad-agent": {
+      "command": "grad-agent",
+      "args": ["server"]
+    }
+  }
+}
+```
+
+## Daily autonomous run (macOS)
+
+The package ships a launchd plist template. To fire every day at 08:00:
+
+```bash
+cp /path/to/grad_agent/templates/com.gradagent.daily.plist ~/Library/LaunchAgents/
+launchctl load ~/Library/LaunchAgents/com.gradagent.daily.plist
+```
+
+Every morning: 3 verified faculty leads, hooks fact-checked against paper abstracts, in your inbox for review.
+
+## What each MCP tool does
+
+| Tool | Purpose |
+|---|---|
+| `run_daily_batch(n, area)` | Full pipeline: verify → recruiting → hook + verify → draft → log |
+| `outreach_log_view(limit)` | Show last N rows of the outreach xlsx |
+| `outreach_mark_sent(prof, uni)` | Flag a row as actually sent to the prof |
+| `sync_catalog(source)` | Pull projects from `github`, `hf`, or `local` |
+| `list_projects_in_catalog()` | Show every project the matcher can see |
+| `list_programs()` | Your target programs |
+| `upcoming_deadlines(days)` | Any program deadline in the next N days |
+| `lor_add / lor_outstanding / lor_mark` | Recommendation-letter tracker |
+| `draft_cold_email(...)` | Manual per-prof draft |
+| `draft_sop(...)` | Compile a Columbia-style SOP PDF for one school |
+| `send_draft_to_me(path)` | Ship any draft file to your review inbox |
+| `discover_profs(area)` | arXiv + OpenReview scan (raw candidates, no verification) |
+
+Blog publishing tools (`publish_article`, `update_article`, ...) are gated behind `blog.enabled: true` in `profile.yaml` and are specific to the author's Turso-backed Next.js portfolio. Most users can ignore them.
+
+## What the agent will not do
+
+- Send any email to a professor. Every send is manual, from your Gmail, after you read the draft.
+- Fabricate a paper claim. The hook goes through a second Claude call that rejects any claim not present in the abstracts, and rewrites.
+- Draft for programs you are ineligible for. If your `degree_status` is `bachelors`, PhD programs that require an MSc first are filtered out.
+
+## Requirements
+
+- Python 3.10+
+- macOS or Linux (Windows untested)
+- `pdflatex` on PATH if you want SOP PDFs (macOS: MacTeX; Ubuntu: `texlive-latex-recommended`)
+- Anthropic API key
+- Gmail (or another SMTP) for the review-mailer
+
+## Where your data lives
+
+Everything is under `~/.grad-agent/` by default, or `$GRAD_AGENT_HOME` if set:
+
+```
+~/.grad-agent/
+  profile.yaml         identity + preferences
+  programs.yaml        target programs
+  .env                 secrets (gitignored)
+  data/
+    outreach_log.xlsx  every prof surfaced or drafted
+    lor_log.xlsx       recommendation-letter tracker
+    catalog.json       synced projects (GitHub + HF + local)
+    db.sqlite          drafts + status
+  drafts/              per-school SOP + email drafts
+```
+
+## Contributing
+
+MIT licensed. PRs welcome for: more program templates, non-Gmail SMTP presets, non-arXiv source adapters, and better prof-verification heuristics.
+
+## Author
+
+Kwabena Obeng · [i-ninte.github.io/portfolio/](https://i-ninte.github.io/portfolio/)

grad_agent-0.1.1/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())